Panduan integrasi Housing Market API
Jadual rujukan, perihalan titik akhir, kod ralat dan contoh dijana daripada spesifikasi API dan kekal dalam bahasa Inggeris dalam setiap bahasa. Nama, parameter dan kod adalah sama di mana-mana.
Titik akhir hartanah dan rujukan medan
GET /v1/properties memulangkan penyenaraian yang diterbitkan bagi satu negara, dengan setiap butiran hartanah yang boleh dilihat oleh kunci Standard.
Setiap medan tergolong dalam salah satu kumpulan ini, seperti yang ditunjukkan dalam lajur dasar.
- Berstruktur (Structured): dipulangkan seperti yang diterbitkan.
- Dikasarkan (Coarsened): nombor rumah tidak pernah dipulangkan, dan bagi rumah yang disenaraikan oleh pemiliknya, koordinat dibundarkan ke tahap kejiranan dan poskod tidak didedahkan.
- Dibersihkan (Scrubbed): teks bebas daripada orang yang menyenaraikan hartanah, dengan alamat e-mel, nombor telefon, alamat web dan nama pengguna aplikasi pemesejan dibuang.
- Terbitan (Derived): dikira oleh API daripada medan lain.
- Diproksi (Proxied): disampaikan melalui API dan bukannya dipautkan secara terus.
Buat masa ini, penyenaraian disediakan tanpa imej: medan images ialah senarai kosong. Pautan imej akan menyusul; gambar asal kekal tersedia secara awam di portal Housing Market.
Tidak pernah dipulangkan: butiran hubungan orang yang menyenaraikan hartanah, identiti ejen dan pemilik, serta apa-apa yang bersifat peribadi bagi sesuatu penyenaraian.
Harga adalah dalam mata wang penyenaraian itu sendiri dan tidak pernah ditukar. Medan tanpa nilai ialah null.
Rekod hartanah
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 |