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. |