Guia de integração da Housing Market API
As tabelas de referência, as descrições dos endpoints, os códigos de erro e os exemplos são gerados a partir da especificação da API e permanecem em inglês em todos os idiomas. Nomes, parâmetros e códigos são idênticos em todos os lugares.
Endpoint de imóveis e referência de campos
GET /v1/properties retorna os anúncios publicados de um país, com todos os detalhes de imóveis que uma chave Standard pode ver.
Cada campo pertence a um destes grupos, indicado na coluna de política.
- Estruturado (Structured): retornado como foi publicado.
- Generalizado (Coarsened): o número do endereço nunca é retornado e, para imóveis anunciados pelo próprio proprietário, as coordenadas são arredondadas para o nível do bairro e o CEP é omitido.
- Higienizado (Scrubbed): texto livre de quem anunciou o imóvel, com endereços de e-mail, números de telefone, endereços web e identificadores de aplicativos de mensagens removidos.
- Derivado (Derived): calculado pela API a partir de outros campos.
- Via proxy (Proxied): servido por meio da API em vez de ser vinculado diretamente.
No momento, os anúncios vêm sem imagens: o campo images é uma lista vazia. Os links das imagens estão a caminho; as fotografias originais continuam públicas nos portais Housing Market.
Nunca retornados: dados de contato de quem anunciou o imóvel, a identidade de corretores e proprietários e qualquer informação privada de um anúncio.
Os preços estão na moeda do próprio anúncio e nunca são convertidos. Um campo sem valor é null.
O registro do imóvel
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 |