Mapaprop
BETA

Zonas

O seu sistema guarda cada imóvel com as suas zonas. O nosso espera as nossas. Antes de nos enviar o primeiro imóvel, você precisa de uma tabela de equivalências —"a minha zona 4471 é 1-1-49-0 da Mapaprop"— que você monta uma vez e depois reutiliza em cada cadastro.

Esta página explica como montá-la. Para isso há duas formas de nos pedir as zonas, e qual delas convém depende do que você estiver fazendo.

As duas formas, e quando usar cada uma

O que você está fazendoUsePor quê
Mapear todo o seu catálogo, uma vez, do seu ladoA lista completaVocê baixa todas as zonas do país e as cruza com as suas sem idas e vindas
Resolver um ramo pontual (uma província, um município)A cascataTrês chamadas pequenas em vez de baixar milhares de linhas

O normal é usar as duas: a lista para o mapeamento inicial, a cascata para consultas pontuais depois.

O catálogo é baixado uma vez e armazenado. Não é um endpoint para chamar a cada cadastro de imóvel: as zonas mudam muito pouco. Guarde o resultado do seu lado e atualize-o de vez em quando — o endpoint ajuda você com isso, veja cache e ETag.

O código de zona: quatro segmentos, sempre

Cada zona tem um código, e esse código é a única coisa que viaja no objeto do imóvel:

1-2-201-0
│ │  │  └─ zone3 — localidade / bairro  (0 se você não descer até esse nível)
│ │  └──── zone2 — município
│ └─────── zone1 — província / estado
└───────── zone0 — país

Sempre quatro segmentos, mesmo quando não há zone3. Quando você não desce até o último nível, vai um 0 ali — não se omite. 1-1-49 não é um código válido; o válido é 1-1-49-0.

Os quatro números também vêm separados em cada linha (zone0, zone1, zone2, zone3), então você pode preencher o objeto sem quebrar a string.

O que é uma zona publicável

Aqui está o que mais surpreende, e convém entender antes de mapear:

As folhas da árvore não são as únicas zonas publicáveis. O município também é publicável por si só.

CódigoO que éPublicável?
1-2-201-0La Matanza (o município inteiro)Sim
1-2-201-117Aldo Bonzi (uma localidade de La Matanza)Sim
1-1-49-0Palermo Hollywood (um bairro de Buenos Aires, sem nível abaixo)Sim

Se você souber a localidade exata, envie a localidade. Se souber apenas o município, envie o município com -0 no final: é um endereço válido e você não precisa inventar uma localidade.

Cada linha traz um campo level que diz qual dos dois é (2 = município, 3 = localidade).

Como cruzar com as suas zonas

Cada linha traz os nomes dos ancestrais como campos próprios, além do path montado:

{
  "code": "1-2-201-117",
  "zone0": 1, "zone1": 2, "zone2": 201, "zone3": 117,
  "level": 3,
  "description": "Aldo Bonzi",
  "zone1Description": "Buenos Aires",
  "zone2Description": "La Matanza",
  "path": "Buenos Aires > La Matanza > Aldo Bonzi"
}
  • Para fazer o match por texto com os seus nomes, use path: ele inclui a ancestralidade, que é o que desambigua. Há dezenas de "San Martín" na Argentina; "Buenos Aires > San Martín" há um.
  • Para montar uma árvore do seu lado, agrupe por zone1 e depois por zone2. Não é preciso quebrar o path nem chamar a cascata: a lista plana já traz tudo.

Guarde o code, não o nome. Os nomes podem ser corrigidos (um acento, uma abreviação); o código não muda. Se o seu mapeamento se apoiar no texto, um dia ele quebra sozinho.

Os países

Antes de mais nada você precisa saber qual número é o seu país, porque todo o resto o exige:

GET https://mapaprop.app/api/action/property-catalog-v1/countries

Sem parâmetros. Devolve os países com o seu ISO e o seu id (o zone0):

[
  { "id": 1, "iso": "AR", "description": "Argentina" },
  { "id": 2, "iso": "ES", "description": "España" }
]

Nos demais endpoints o país vai pelo ISO (country=AR), não pelo número.

Autenticação

Todo o catálogo exige Authorization: Bearer {o seu access_token} com o escopo property-api-catalog.

O catálogo é servido a partir de mapaprop.app/api/action/…, não de property-api.mapaprop.com. São dois hosts e isso é proposital: o catálogo fica onde ficam os dados. O token é o mesmo para os dois, você não precisa de credenciais separadas.

Se você receber um 403, é o token ou o escopo; se receber um 404, é o método ou a URL (todos estes endpoints são GET).

Veja também