--- title: "Spacious API: JSON data, 6 endpoints, 1 credit per call" description: "Spacious API for Hong Kong homes to buy or rent, listings, buildings, neighbourhoods and licensed estate agencies as JSON. 1 credit per successful call." url: https://perceptlayer.com/apis/spacious --- [APIs](https://perceptlayer.com/apis) / [Real estate](https://perceptlayer.com/verticals/real-estate) / Spacious 1 credit per call 6 endpoints 3 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](https://perceptlayer.com/signup) 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 OK JSON X-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. | # | id integer | name string | licence string | | --- | --- | --- | --- | | 1 | 1837 | UNIVERSAL (T.W.) PROPERTY AGENCY LIMITED | C-037504 | | 2 | 1844 | UNIVERSAL (S.T.) PROPERTY AGENCY LIMITED | C-026287 | Recorded from our API · 2 items shown · 3 datapoints per item GET /v1/spacious/agencies-search?query=universal&limit=2 3 datapoints ### Identity - id integer - name string ### Other - licence string Playground ## Run this API cURL shell ``` 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`](https://perceptlayer.com/apis/spacious/agencies-search) | `query` +1 optional | 1 credit | | [GET `/v1/spacious/agency`](https://perceptlayer.com/apis/spacious/agency) | `id` +2 optional | 1 credit | | [GET `/v1/spacious/autocomplete`](https://perceptlayer.com/apis/spacious/autocomplete) | `query` +2 optional | 1 credit | | [GET `/v1/spacious/building`](https://perceptlayer.com/apis/spacious/building) | `id` | 1 credit | | [GET `/v1/spacious/listing`](https://perceptlayer.com/apis/spacious/listing) | `path` | 1 credit | | [GET `/v1/spacious/search`](https://perceptlayer.com/apis/spacious/search) | `mode` +15 optional | 1 credit | Overview ## About the Spacious API ## 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 estate JSON REST MCP ### More real estate APIs [28Hse](https://perceptlayer.com/apis/28hse) [4zida](https://perceptlayer.com/apis/4zida) [591](https://perceptlayer.com/apis/591-house) [99.co](https://perceptlayer.com/apis/99co) [99acres](https://perceptlayer.com/apis/99acres) [Adondevivir](https://perceptlayer.com/apis/adondevivir) [Apartment List](https://perceptlayer.com/apis/apartment-list) [Apartments.com](https://perceptlayer.com/apis/apartments-com) [Aqar](https://perceptlayer.com/apis/aqar) [Aqarmap](https://perceptlayer.com/apis/aqarmap) [Argenprop](https://perceptlayer.com/apis/argenprop) [athome](https://perceptlayer.com/apis/athome) 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](https://perceptlayer.com/signup) [Read the docs](https://docs.perceptlayer.com)