BETA

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

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