Housing Market API 整合指南
參考表格、端點說明、錯誤代碼和範例皆由 API 規格產生，在所有語言版本中均保留英文。名稱、參數和代碼在各處完全相同。
物件端點與欄位參考
GET /v1/properties 會傳回單一國家的已刊登房源，並包含標準版金鑰可查看的所有物件詳細資訊。
每個欄位都屬於下列其中一個群組，群組顯示於政策欄中。
- 結構化 (Structured)：依刊登時的原樣傳回。
- 粗略化 (Coarsened)：門牌號碼一律不傳回；對於屋主自行刊登的房屋，座標會取整至街區層級，且不提供郵遞區號。
- 已清理 (Scrubbed)：刊登者撰寫的自由文字，其中的電子郵件地址、電話號碼、網址和通訊軟體帳號皆已移除。
- 衍生 (Derived)：由 API 根據其他欄位計算而得。
- 代理 (Proxied)：透過 API 提供，而非直接連結。
房源目前不含圖片：images 欄位為空清單。圖片連結將於日後提供；原始照片仍公開展示於 Housing Market 各入口網站。
一律不傳回：刊登者的聯絡資料、仲介與屋主的身分，以及任何屬於房源私人資訊的內容。
價格以房源本身的幣別表示，且一律不換算。沒有值的欄位為 null。
物件紀錄
GET /v1/properties: List published properties in one country
| Field | Type | Policy | Description |
|---|---|---|---|
id required | string | Structured | Stable identifier of the listing. Treat it as opaque. |
country required | string | Structured | ISO 3166-1 alpha-2 code of the country the listing is in. |
listing_type required | string | Structured | What the listing offers. Requesting listing_type=all returns every value. sale rent vacation_rental co_living |
property_type required | string | null | Structured | The kind of property in lower case, for example condominium or house. Null when the listing does not state one. |
province | string | null | Structured | Name of the province or state. |
province_id | integer | null | Structured | Identifier of the province or state, for the province_id filter. |
city | string | null | Structured | Name of the city. |
city_id | integer | null | Structured | Identifier of the city, for the city_id filter. |
area | string | null | Structured | Name of the district or area. |
area_id | integer | null | Structured | Identifier of the district or area, for the area_id filter. |
address | string | null | Coarsened | Street name or locality line. The street number is never included. |
post_code | string | null | Coarsened | Postal code. Null for owner-listed homes. |
latitude | number | null | Coarsened | Latitude in decimal degrees. For owner-listed homes it is rounded so that it identifies a neighbourhood, not a building; see location_precision. |
longitude | number | null | Coarsened | Longitude in decimal degrees. Same precision rule as latitude. |
location_precision required | string | Derived | approximate when the coordinates and post code have been coarsened because the home is listed by its owner; otherwise exact. exact approximate |
price | number | null | Structured | Published price in the listing's own currency. For rent listings it is the published amount per month. Never converted. |
price_max | number | null | Structured | Upper end when the listing publishes a price range; otherwise null. |
currency required | string | null | Structured | ISO 4217 code of the currency price and price_max are in. Null when the listing states none. |
bedrooms | number | null | Structured | Number of bedrooms. |
bathrooms | number | null | Structured | Number of bathrooms. |
rooms | number | null | Structured | Total number of rooms, where the listing states it. |
living_area | number | null | Structured | Living area in the unit the lister used. Use living_area_sqm to compare listings. |
living_area_sqm | number | null | Structured | Living area in square metres. |
lot_area | number | null | Structured | Plot area in the unit the lister used. Use lot_area_sqm to compare listings. |
lot_area_sqm | number | null | Structured | Plot area in square metres. |
build_year | integer | null | Structured | Year the property was built. |
published_date required | string | null (date-time) | Structured | When the listing was first published. Null when the portal does not record it. |
last_updated required | string | null (date-time) | Structured | When the listing last changed, or published_date when no change is recorded. This is the value updated_since compares. |
features | array of string | Structured | Feature names, for example the facilities of the building. |
appliances | array of string | Structured | Appliance names included with the property. |
neighbourhood | array of string | Structured | Names of neighbourhood features, such as nearby transport. |
tags | array of string | Structured | Tag names the lister attached to the listing. |
developer | string | null | Structured | Name of the development company, where the listing names one. Never a person. |
summary | string | null | Scrubbed | Short description. Email addresses, phone numbers, web addresses and messaging handles are removed. |
description | string | null | Scrubbed | Full description as plain text. Email addresses, phone numbers, web addresses and messaging handles are removed. |
location_text | string | null | Scrubbed | The lister's description of the location, scrubbed in the same way. |
images required | array of Image | Proxied | Watermarked, signed, expiring photographs. Never a direct storage or CDN address. Empty until the image service is available. |
images[]
| Field | Type | Description |
|---|---|---|
url required | string (uri) | Signed address of the watermarked image. Valid for your key only, until expires_at. |
expires_at required | string (date-time) | When the URL stops working. |
position required | integer | Order of the photograph on the listing. 1 is the lead photograph. |
GET /v1/properties/{id}
Get one published property
Returns one published listing by the id a listing page carried, in the same shape. The country must be the listing's own country and one your key covers. A listing that has been withdrawn, an id from another country, and an id that never existed all return not_found.
Parameters
| Parameter | Type | Required | Values | Description |
|---|---|---|---|---|
id | string | yes | The id of a listing, exactly as a listing page returned it. | |
country | string | yes | pattern ^[A-Z]{2}$ | ISO 3166-1 alpha-2 code of the country, for example TH. A country
outside your subscription is refused with country_not_entitled. |
Responses
| Status | Description | Error codes |
|---|---|---|
200 | The listing. | |
400 | The request is invalid. | invalid_parameter invalid_cursor |
401 | The key is missing, unknown or revoked. | unauthenticated |
403 | The request is refused for the key, the address or the country. | country_not_entitled ip_not_allowed key_paused |
404 | The listing does not exist, is not in that country, or has been withdrawn. | not_found |
429 | A rate limit or a quota has been reached. | rate_limited quota_exceeded |
500 | Something went wrong on our side. | internal_error |
503 | The service cannot answer right now. | service_unavailable |