GET /property-catalog-v1/zones
Devolve todas as zonas publicáveis de um país, planas e paginadas. É o endpoint do mapeamento em lote: você o chama poucas vezes, guarda o resultado e monta a sua tabela de equivalências.
Antes de usá-lo, leia Zonas: lá está o que é uma zona publicável e qual é o formato do código.
| Informações do recurso | |
|---|---|
| Autenticação | Obrigatória (Token de API, Bearer) |
| Escopo | property-api-catalog |
| HTTP Method | GET |
| Response | JSON |
| Version | 1 |
URL do recurso
https://mapaprop.app/api/action/property-catalog-v1/zones
Parâmetros
| Key | Type | Required | Descrição |
|---|---|---|---|
| country | string | sim | O código ISO do país, 2 letras (AR, ES, MX…). Você os obtém em /countries |
| from | int | não | A partir de qual linha. Por padrão 0 |
| size | int | não | Quantas linhas. Por padrão 1000, máximo 5000 |
Código de exemplo
GET /api/action/property-catalog-v1/zones?country=AR&from=0&size=1000 HTTP/1.1
Host: mapaprop.app
Authorization: Bearer {access_token}
Resposta
{
"total": 7526,
"from": 0,
"size": 1000,
"zones": [
{
"code": "1-2-201-0",
"zone0": 1, "zone1": 2, "zone2": 201, "zone3": 0,
"level": 2,
"description": "La Matanza",
"zone1Description": "Buenos Aires",
"zone2Description": "La Matanza",
"path": "Buenos Aires > La Matanza"
}
]
}
| Campo | Tipo | Descrição |
|---|---|---|
| total | int | Quantas zonas o país tem no total, não nesta página. É com isso que você sabe quando terminou |
| from | int | O from que você pediu |
| size | int | O size que você pediu |
| zones | array | As linhas desta página |
E dentro de cada linha:
| Campo | Tipo | Descrição |
|---|---|---|
| code | string | O valor que vai no objeto do imóvel. Sempre quatro segmentos |
| zone0 · zone1 · zone2 · zone3 | int | Os mesmos quatro números, separados, para você não precisar quebrar o code |
| level | int | 2 = município · 3 = localidade/bairro |
| description | string | O nome desta zona |
| zone1Description | string | O nome da sua província/estado |
| zone2Description | string | O nome do seu município |
| path | string | A ancestralidade montada, Província > Município > Localidade. Para o match por texto |
Paginar
A ordem é estável entre chamadas, então você pode percorrê-la página por página sem medo de que uma linha se repita ou se perca. O padrão é:
from=0 size=1000
from=1000 size=1000
from=2000 size=1000
…até que from >= total
A Argentina são 8 chamadas; a Espanha, 13. Um from além do final devolve 200 com zones
vazio, não um erro.
Cache e ETag
Cada resposta traz um ETag. Se na chamada seguinte você o enviar em If-None-Match e o catálogo
não tiver mudado, respondemos 304 Not Modified sem corpo:
GET /api/action/property-catalog-v1/zones?country=AR&size=1000 HTTP/1.1
Authorization: Bearer {access_token}
If-None-Match: "1-0-1000-46f144e43a1443ed"
HTTP/1.1 304 Not Modified
ETag: "1-0-1000-46f144e43a1443ed"
Guarde o ETag de cada página junto com os seus dados: o ETag identifica aquela página, não o
país inteiro. Se você enviar o da página 1 pedindo a página 2, vai receber um 200 com os dados —
correto, mas não economiza nada.
Atualizar o catálogo é barato. Em vez de decidir de quanto em quanto tempo baixá-lo de novo, peça-o com o ETag que você guardou: desde que nada tenha mudado, são 304s e pronto. Se algo mudou, chega a versão nova.
Erros
| HTTP | error | O que aconteceu |
|---|---|---|
| 400 | REQUIRED_INPUT | Falta country |
| 400 | INVALID_INPUT | O ISO não corresponde a nenhum país, ou from é negativo, ou size é 0 |
| 400 | INPUT_TOO_LONG | Você pediu mais de 5000 por chamada |
| 403 | INVALID_PERMISSION | O seu token não tem o escopo property-api-catalog |
| 403 | CREDENTIALS_DOES_NOT_MATCH | Você não enviou token, ou ele venceu |
| 404 | — | Você usou outro método: este endpoint é GET |