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 |