GET /property-catalog-v1/zones
Devuelve todas las zonas publicables de un país, planas y paginadas. Es el endpoint del mapeo en lote: lo llamás unas pocas veces, guardás el resultado y armás tu tabla de equivalencias.
Antes de usarlo, leé Zonas: ahí está qué es una zona publicable y qué formato tiene el código.
| Información del recurso | |
|---|---|
| Autenticación | Requerida (Token de API, Bearer) |
| Scope | property-api-catalog |
| HTTP Method | GET |
| Response | JSON |
| Version | 1 |
URL del recurso
https://mapaprop.app/api/action/property-catalog-v1/zones
Parámetros
| Key | Type | Required | Descripción |
|---|---|---|---|
| country | string | sí | El código ISO del país, 2 letras (AR, ES, MX…). Los conseguís en /countries |
| from | int | no | Desde qué fila. Por defecto 0 |
| size | int | no | Cuántas filas. Por defecto 1000, máximo 5000 |
Código de ejemplo
GET /api/action/property-catalog-v1/zones?country=AR&from=0&size=1000 HTTP/1.1
Host: mapaprop.app
Authorization: Bearer {access_token}
Respuesta
{
"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 | Descripción |
|---|---|---|
| total | int | Cuántas zonas tiene el país en total, no en esta página. Es con lo que sabés cuándo terminaste |
| from | int | El from que pediste |
| size | int | El size que pediste |
| zones | array | Las filas de esta página |
Y dentro de cada fila:
| Campo | Tipo | Descripción |
|---|---|---|
| code | string | El valor que va en el objeto de la propiedad. Siempre 4 segmentos |
| zone0 · zone1 · zone2 · zone3 | int | Los mismos cuatro números, sueltos, para que no tengas que partir el code |
| level | int | 2 = partido/municipio · 3 = localidad/barrio |
| description | string | El nombre de esta zona |
| zone1Description | string | El nombre de su provincia/estado |
| zone2Description | string | El nombre de su partido/municipio |
| path | string | La ancestría armada, Provincia > Partido > Localidad. Para matchear por texto |
Resolver UNA zona, por su código
Cuando ya tenés el código y sólo querés saber si sigue siendo válido, no hace falta bajar el catálogo:
GET /property-catalog-v1/zones/{code}
curl -H "Authorization: Bearer $TOKEN" \
https://mapaprop.app/api/action/property-catalog-v1/zones/1-1-46-0
| Resultado | Qué significa |
|---|---|
200 + la fila | la zona existe, con su description, su path y su level |
400 · INVALID_INPUT | no existe — ni esa zona, ni esa jerarquía |
El code va con sus 4 segmentos siempre, igual que en el listado: 1-1-49-0, no 1-1-49.
Sirve para dos cosas: revalidar una clave vieja de tu tabla de equivalencias, y resolver el código que te devolvió el verificador cuando una zona no existe.
Es la misma consulta que hacemos nosotros al verificar una propiedad. Si el verificador te dijo que una zona no existe, acá vas a ver exactamente lo mismo.
Paginar
El orden es estable entre llamadas, así que podés recorrerlo de a páginas sin miedo a que una fila se repita o se pierda. El patrón es:
from=0 size=1000
from=1000 size=1000
from=2000 size=1000
…hasta que from >= total
Argentina son 8 llamadas; España, 13. Un from más allá del final devuelve 200 con zones
vacío, no un error.
Caché y ETag
Cada respuesta trae un ETag. Si en la llamada siguiente lo mandás en If-None-Match y el catálogo
no cambió, te contestamos 304 Not Modified sin cuerpo:
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"
Guardate el ETag de cada página junto con sus datos: el ETag identifica esa página, no el país
entero. Si mandás el de la página 1 pidiendo la página 2, te va a responder 200 con los datos —
correcto, pero no te ahorra nada.
Refrescar el catálogo es barato. En vez de decidir cada cuánto rebajarlo, pedilo con el ETag que guardaste: si no cambió nada, son 304s y listo. Si cambió, te llega la versión nueva.
Errores
| HTTP | error | Qué pasó |
|---|---|---|
| 400 | REQUIRED_INPUT | Falta country |
| 400 | INVALID_INPUT | El ISO no corresponde a ningún país, o from es negativo, o size es 0 |
| 400 | INPUT_TOO_LONG | Pediste más de 5000 por llamada |
| 403 | INVALID_PERMISSION | Tu token no tiene el scope property-api-catalog |
| 403 | CREDENTIALS_DOES_NOT_MATCH | No mandaste token, o venció |
| 404 | — | Usaste otro método: este endpoint es GET |
Ver también
- Zonas — el concepto y el formato del código
- La cascada — para resolver una rama sin bajar todo