1 credit per call6 endpoints3 datapoints

Spacious API

Spacious API for Hong Kong homes to buy or rent, listings, buildings, neighbourhoods and licensed estate agencies as JSON. 1 credit per successful call.

Get a free API key Run it below

Spacious

GET/v1/spacious/agencies-search?query=universal&limit=2

{
  "success": true,
  "data": {
    "query": "universal",
    "results": [
      {
        "id": 1837,
        "name": "UNIVERSAL (T.W.) PROPERTY AGENCY LIMITED",
        "licence": "C-037504"
      },
      {
        "id": 1844,
        "name": "UNIVERSAL (S.T.) PROPERTY AGENCY LIMITED",
        "licence": "C-026287"
      }
    ]
  },
  "meta": {
    "endpoint_family": "agency_search",
    "request_id": "req_fa2bc7125cbc4cbf9cac3cc073575f88",
    "credits_charged": 1,
    "credits_remaining": 1811
  }
}

200 OKJSONX-Credits-Used: 1

Recorded from our API and shortened.

Sample data

What one call returns

A recorded run of agencies-search: the fields and shapes you will get, shortened to 2 items.

#	idinteger	namestring	licencestring
1	1837	UNIVERSAL (T.W.) PROPERTY AGENCY LIMITED	C-037504
2	1844	UNIVERSAL (S.T.) PROPERTY AGENCY LIMITED	C-026287

[
  {
    "id": 1837,
    "name": "UNIVERSAL (T.W.) PROPERTY AGENCY LIMITED",
    "licence": "C-037504"
  },
  {
    "id": 1844,
    "name": "UNIVERSAL (S.T.) PROPERTY AGENCY LIMITED",
    "licence": "C-026287"
  }
]

id,name,licence
1837,UNIVERSAL (T.W.) PROPERTY AGENCY LIMITED,C-037504
1844,UNIVERSAL (S.T.) PROPERTY AGENCY LIMITED,C-026287

Recorded from our API · 2 items shown · 3 datapoints per itemGET /v1/spacious/agencies-search?query=universal&limit=2

3 datapoints

Identity

idinteger
namestring

Other

licencestring

Playground

Run this API

cURLshell

curl "https://api.perceptlayer.com/v1/spacious/agencies-search?query=universal&limit=2" \
  -H "X-API-Key: $API_KEY"

Spacious · 6 endpoints

Endpoints

Every endpoint takes the same key. Open one for its parameters and an example request.

Endpoint	Required parameters	Cost
GET`/v1/spacious/agencies-search`	`query`+1 optional	1 credit
GET`/v1/spacious/agency`	`id`+2 optional	1 credit
GET`/v1/spacious/autocomplete`	`query`+2 optional	1 credit
GET`/v1/spacious/building`	`id`	1 credit
GET`/v1/spacious/listing`	`path`	1 credit
GET`/v1/spacious/search`	`mode`+15 optional	1 credit

Overview

What you can get

The Spacious API returns Spacious property data as JSON through 6 endpoints.

Search: search takes a mode (buy or rent), with locale (en or zh-tw), bedrooms (0 to 4), min_bedrooms (1 to 4), bathrooms (1 or 2), min_bathrooms (1 or 2), price_min, price_max, area_min, area_max, area_type (net or gross), property_type (village_house or detached_house), neighbourhood_id, building_id, page and sort (relevance, latest, price_low, price_high, area_low, area_high, unit_price_low or unit_price_high).
Listings and buildings: listing takes a path; building takes an id.
Agencies: agencies-search takes a query, with limit; agency takes an id, with mode (buy or rent) and page.
Autocomplete: autocomplete takes a query, with type (building or neighbourhood) and limit.

The recorded agencies-search for "universal" with limit=2 returns the query and results, each with the agency's id, name and licence number.

How a call works

Find an agency, then its listings: GET /v1/spacious/agencies-search?query=universal&limit=2 with your key in the X-API-Key header. Each result's id is what agency takes, with mode=buy or mode=rent for the agency's listings. To search homes, call GET /v1/spacious/search?mode=rent&bedrooms=2&price_min=20000&price_max=30000. Every successful call costs 1 credit; failed calls cost nothing.

Real estateJSONRESTMCP

More real estate APIs

Use cases

Track asking rents and prices by bedroom count in Hong Kong

Use the Spacious API to track asking rents and prices by bedroom count in Hong Kong

Rank listings by unit price with `sort=unit_price_low`, on net or gross `area_type`

Use the Spacious API to rank listings by unit price with `sort=unit_price_low`, on net or gross `area_type`

Watch every listing in one building with `building_id`

Use the Spacious API to watch every listing in one building with `building_id`

Check an estate agency's licence number before contacting it

Use the Spacious API to check an estate agency's licence number before contacting it

FAQ

Questions

Do I need a Spacious account?

No. You call this Spacious API with your Perceptlayer key in the `X-API-Key` header, with no Spacious login.

How much does the Spacious API cost?

Each successful call costs one credit. New accounts get free credits to start, and credit packs bring the price down as you scale.

What format are responses in?

Every endpoint returns JSON, with no HTML parsing on your side.

Can I get results in Chinese?

Yes. Set `locale` to zh-tw on `search`, or en for English.

Should I build a Spacious scraper instead?

You can, but a Spacious scraper is code you maintain: page changes break it, requests get blocked, and Spacious's terms govern how you collect data. The Spacious API gives you 6 endpoints of named JSON fields for 1 credit per successful call, and failed calls cost nothing. A scraper makes sense only for data these endpoints don't return, so check the response in the playground on this page first.

Try the Spacious API with 100 free credits

No credit card. Failed calls are never billed.

Get a free API key Read the docs