Guide d’intégration de la Housing Market API
Les tableaux de référence, les descriptions des points de terminaison, les codes d’erreur et les exemples sont générés à partir de la spécification de l’API et restent en anglais dans toutes les langues. Les noms, paramètres et codes sont identiques partout.
Points de terminaison Insights
Formule Avancée uniquementLes points de terminaison Insights renverront des données de marché agrégées avec la formule Avancée. Bientôt disponible : ces points de terminaison ne sont pas encore actifs.
Dès le lancement d’Insights, une clé Standard qui appelle un point de terminaison Insights sera refusée avec upgrade_required. Passez à la formule supérieure dans la console, et la même clé fonctionnera alors.
Chaque valeur est un agrégat pour un lieu et une période. Les personnes, prospects, agents et annonces pris individuellement ne sont jamais renvoyés.
Pour protéger la vie privée, une cellule calculée à partir de moins de 10 événements sous-jacents est masquée. Elle est tout de même renvoyée, avec suppressed défini sur true et ses valeurs définies sur null, afin que votre série conserve sa structure.
Les prix sont exprimés dans la devise locale du pays et ne sont jamais convertis : les chiffres de pays différents ne peuvent donc pas être comparés en termes monétaires.
Pour chaque indicateur, les données de marché de tiers nomment leur éditeur et renvoient vers la source.
Paramètres communs aux points de terminaison 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. |
Points de terminaison
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. |