Housing Market API 整合指南
參考表格、端點說明、錯誤代碼和範例皆由 API 規格產生，在所有語言版本中均保留英文。名稱、參數和代碼在各處完全相同。
Insights 端點
僅限進階版Insights 端點將為進階版提供彙總的市場資料。即將推出：這些端點尚未上線。
Insights 推出後，標準版金鑰呼叫 Insights 端點時會遭拒絕並傳回 upgrade_required。在主控台升級後，同一把金鑰即可使用。
每個值都是某個地點在某段期間內的彙總值。一律不會傳回個人、潛在客戶、仲介或單一房源。
為保護隱私，由少於 10 個基礎事件構成的儲存格會被隱藏。該儲存格仍會傳回，其 suppressed 設為 true，各值設為 null，讓您的資料序列維持原有結構。
價格以該國的當地貨幣表示，且一律不換算，因此不同國家的數字無法作為金額相互比較。
第三方市場資料會為每項指標註明發布者，並連結至來源。
Insights 端點共用的參數
| Parameter | Type | Required | Values | Description |
|---|---|---|---|---|
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. |
level | string | no | country province citydefault country | How finely to group the cells. country is the default. |
province_id | integer | no | min 1 | Return only listings in this province or state, by the province_id listings carry. |
city_id | integer | no | min 1 | Return only listings in this city, by the city_id listings carry. |
listing_type | string | no | all sale rentdefault all | Which kind of listing to include. all is the default. |
from | string (date) | no | First day of the period, as YYYY-MM-DD. | |
to | string (date) | no | Last day of the period, as YYYY-MM-DD. | |
granularity | string | no | day week monthdefault month | Length of each period. month is the default. |
limit | integer | no | default 50min 1max 100 | Page size. At most the maximum shown; larger values are refused with invalid_parameter. |
cursor | string | no | The next_cursor of the previous page. Opaque: do not parse it, store
it, or build one. It is bound to your key and to the filters of the
request that produced it, and a cursor used with different filters is
refused with invalid_cursor. |
端點
GET /v1/insights/search-volume Advanced only
Search volume by place and period
How many property searches were run on the portals for a place and a period. Counts only; no search phrase and no searcher is ever returned.
Each item of data
| Field | Type | Description |
|---|---|---|
period_start required | string (date) | First day of the period. |
period_end required | string (date) | Last day of the period. |
geography required | Geography | |
suppressed required | boolean | True when the cell was too small to publish. Its values are null. |
searches required | integer | null | Number of property searches. Null when suppressed. |
GET /v1/insights/lead-volume Advanced only
Lead volume by place and period
How many enquiries were made about listings in a place and a period. Counts only. Cells with fewer underlying leads than the suppression threshold are returned with suppressed: true and no value.
Each item of data
| Field | Type | Description |
|---|---|---|
period_start required | string (date) | First day of the period. |
period_end required | string (date) | Last day of the period. |
geography required | Geography | |
suppressed required | boolean | True when the cell was too small to publish. Its values are null. |
leads required | integer | null | Number of enquiries made about listings in the cell. Null when suppressed. |
GET /v1/insights/prices Advanced only
Prices by place and period
Median asking prices for a place and a period, in the local currency of the country. Prices are never converted between currencies, so a figure from one country cannot be compared with a figure from another.
| Parameter | Type | Required | Values | Description |
|---|---|---|---|---|
property_type | string | no | Return only this property type, for example condominium. The value
is the property_type that listings carry; an unknown value returns
an empty page. |
Each item of data
| Field | Type | Description |
|---|---|---|
period_start required | string (date) | First day of the period. |
period_end required | string (date) | Last day of the period. |
geography required | Geography | |
suppressed required | boolean | True when the cell was too small to publish. Its values are null. |
currency required | string | ISO 4217 code of the local currency. Prices are never converted. |
median_price required | number | null | Median asking price. Null when suppressed. |
median_price_per_sqm required | number | null | Median asking price per square metre. Null when suppressed. |
listing_count required | integer | null | Number of listings the medians are based on. Null when suppressed. |
GET /v1/insights/property-counts Advanced only
Property counts by place and period
How many published listings there were in a place and a period, and how many were new.
| Parameter | Type | Required | Values | Description |
|---|---|---|---|---|
property_type | string | no | Return only this property type, for example condominium. The value
is the property_type that listings carry; an unknown value returns
an empty page. |
Each item of data
| Field | Type | Description |
|---|---|---|
period_start required | string (date) | First day of the period. |
period_end required | string (date) | Last day of the period. |
geography required | Geography | |
suppressed required | boolean | True when the cell was too small to publish. Its values are null. |
active_listings required | integer | null | Number of published listings in the cell. Null when suppressed. |
new_listings required | integer | null | Number of listings first published in the period. Null when suppressed. |
GET /v1/insights/activity Advanced only
Activity levels by place and period
How much attention listings in a place received in a period: views and enquiries, summed over every listing in the cell. Cells with fewer underlying events than the suppression threshold are returned with suppressed: true and no values.
Each item of data
| Field | Type | Description |
|---|---|---|
period_start required | string (date) | First day of the period. |
period_end required | string (date) | Last day of the period. |
geography required | Geography | |
suppressed required | boolean | True when the cell was too small to publish. Its values are null. |
views required | integer | null | Listing views in the cell. Null when suppressed. |
enquiries required | integer | null | Enquiries about listings in the cell. Null when suppressed. |
GET /v1/insights/market-data Advanced only
Third-party market data for a country
Published indicators from named third parties, such as central-bank mortgage rates or land-registry volumes, each with its publisher and a link to the source. A source appears here only after its licence has been checked for this use.
Each item of data
| Field | Type | Description |
|---|---|---|
indicator required | string | Stable name of the indicator, for example mortgage_rate. |
value required | number | The published figure. |
unit required | string | Unit of value, for example percent. |
period_start required | string (date) | First day the figure covers. |
period_end required | string (date) | Last day the figure covers. |
source required | object | Where the figure comes from. |