# Spacious HK Search API

<p>Search homes for sale or rent on Spacious, the Hong Kong property portal. Filter by bedrooms, bathrooms, price, net or gross area, property type, neighbourhood and building, sort and page through the results, 14 listings per page. Every returned listing satisfies every filter you send, and the response lists the filters that were applied. A page past the last page returns an empty list with the page you asked for. The total and the total pages are not known there. Each listing carries the id, path, building, neighbourhood, price as text and as a number in HKD, net and gross area, price per square foot, bedrooms, bathrooms, position, photos and badges. Rent is HK$ per month, sale is the total in HK$. Sale prices on the cards are rounded by the site, for example HK$7.68M. The listing endpoint returns the exact price. When you sort by price, listings with the same price can repeat across pages. Open a listing with its path for the full record.</p>

- **Documentation:** [https://scrappa.co/docs/spacious-hk-api/spacious_hk_search](https://scrappa.co/docs/spacious-hk-api/spacious_hk_search)
- **API group:** Spacious HK API
- **Endpoint:** `GET https://scrappa.co/api/spacious-hk/search`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `mode` | string | Yes | `buy` for homes for sale, `rent` for homes for rent. |
| `bedrooms` | integer | No | Exact number of bedrooms: `0` (studio), `1`, `2`, `3` or `4`. Not with `min_bedrooms`. |
| `min_bedrooms` | integer | No | That many bedrooms or more: `1`, `2`, `3` or `4`. Not with `bedrooms`. |
| `bathrooms` | integer | No | Exact number of bathrooms: `1` or `2`. Listings without a bathroom count are not returned. |
| `min_bathrooms` | integer | No | That many bathrooms or more: `1` or `2`. Not with `bathrooms`. |
| `price_min` | integer | No | Lowest price in HKD. Rent is per month, sale is the total price. |
| `price_max` | integer | No | Highest price in HKD. Rent is per month, sale is the total price. |
| `area_min` | integer | No | Smallest area in square feet. The `area_type` says which area. |
| `area_max` | integer | No | Largest area in square feet. The `area_type` says which area. |
| `area_type` | string | No | `net` (default) or `gross`. Used with `area_min` and `area_max`. |
| `property_type` | string | No | `village_house` or `detached_house`. Leave out for all homes. The site decides what counts as a village or detached house. |
| `neighbourhood_id` | string | No | Neighbourhood id from the autocomplete endpoint with `type=neighbourhood`. One id, or up to 3 ids separated by commas. |
| `building_id` | string | No | Building id from the autocomplete endpoint with `type=building`. Send the `neighbourhood_id` of the same result too. |
| `sort` | string | No | `latest` (default), `relevance`, `price_low`, `price_high`, `area_low`, `area_high`, `unit_price_low` or `unit_price_high`. Listings with the same price can repeat across pages when you sort by price, so use `latest` to page through everything. |
| `locale` | string | No | `en` (default) or `zh-tw`. Changes the language of names and links. |
| `page` | integer | No | Page number, 1-based, up to 3000. 14 listings per page. |

## Example response

```json
{
    "data": {
        "mode": "rent",
        "page": 1,
        "total": 1209,
        "filters": {
            "sort": "latest",
            "locale": "en",
            "bedrooms": 2,
            "price_max": 30000,
            "price_min": 20000
        },
        "listings": [
            {
                "id": "15093516",
                "url": "https://www.spacious.hk/en/hong-kong/36-mid-levels-central/151318--vantage-park-block-2/15093516-flat-liq921-2-beds",
                "path": "/en/hong-kong/36-mid-levels-central/151318--vantage-park-block-2/15093516-flat-liq921-2-beds",
                "price": 40000,
                "title": "Vantage Park Block 2",
                "images": [
                    "https://cdn.spacious.hk/uploads/property_image/143825205/image/thumb_q30-0d1e2f.jpg"
                ],
                "bedrooms": 2,
                "building": {
                    "id": 151318,
                    "url": "https://www.spacious.hk/en/hong-kong/n/36-mid-levels-central/b/151318--vantage-park-block-2",
                    "name": "Vantage Park Block 2"
                },
                "currency": "HKD",
                "latitude": 22.2793755,
                "longitude": 114.150727,
                "price_text": "HK$40,000",
                "image_count": 11,
                "neighbourhood": {
                    "id": 36,
                    "url": "https://www.spacious.hk/en/hong-kong/n/36-mid-levels-central",
                    "name": "Mid Levels Central"
                },
                "net_area_sqft": 611,
                "price_per_sqft": 65
            }
        ],
        "per_page": 14,
        "total_pages": 87
    },
    "meta": {
        "billable": true,
        "endpoint_family": "search"
    },
    "success": true
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
|  | The listing, building or agency does not exist or is no longer online. This response is not billable. |  |
|  | A parameter is missing or invalid. This response is not billable. |  |
|  | Spacious HK is temporarily unavailable, or its answer did not match the request, for example another page or an ignored filter. Retry the request. This response is not billable. |  |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)