La API Georef permite realizar consultas múltiples en una sola petición utilizando el método POST. Esta funcionalidad, disponible para todos los recursos, permite acelerar el procesamiento cuando se desea normalizar o consultar grandes volúmenes de datos.

¿Cómo funciona?

Cada recurso de la API tiene una versión POST que admite una lista de objetos en el cuerpo de la consulta. Estos objetos contienen los mismos parámetros que se usarían en una consulta GET, con la excepción de:

• El parámetro formato, que no puede modificarse y siempre toma el valor json.
• Todos los parámetros se envían en el cuerpo del mensaje HTTP (JSON) y no en la URL.

Esto permite enviar cientos de consultas en una sola solicitud HTTP, optimizando tiempos y consumo de red.

Equivalencia entre GET y POST

Las siguientes tres consultas GET:

GET https://apis.datos.gob.ar/georef/api/v2.0/provincias?nombre=cordoba&campos=nombre
GET https://apis.datos.gob.ar/georef/api/v2.0/provincias?nombre=chaco&campos=nombre
GET https://apis.datos.gob.ar/georef/api/v2.0/provincias?nombre=san luis&campos=nombre

Pueden resumirse en esta única consulta POST:

POST https://apis.datos.gob.ar/georef/api/v2.0/provincias
Content-Type: application/json

{
  "provincias": [
    { "nombre": "cordoba", "campos": "nombre" },
    { "nombre": "chaco", "campos": "nombre" },
    { "nombre": "san luis", "campos": "nombre" }
  ]
}

La respuesta será una lista de objetos, agrupados dentro del campo resultados, manteniendo el mismo formato de respuesta que las consultas GET.

Límites de uso

• Se puede enviar hasta 1000 consultas por petición.
• La suma de los valores de max para todas las consultas no debe superar 5000.

Por ejemplo:

• 1000 consultas con max: 5 (1000×5 = 5000)
• 100 consultas con max: 50
• 1000 consultas con max: 10 (excede los 5000 resultados posibles)

Buenas prácticas

Cuando se utiliza esta funcionalidad para normalizar grandes volúmenes de datos, es recomendable agregar el parámetro max: 1 a cada consulta. Esto limita la respuesta a solo el resultado más relevante, mejorando tiempos de respuesta y reduciendo el volumen de datos transmitido.

Ejemplos prácticos

A continuación se presentan ejemplos utilizando curl. También podés encontrar ejemplos en Python en la sección correspondiente.

Búsqueda de municipios en lote

curl -X POST "https://apis.datos.gob.ar/georef/api/v2.0/municipios" \
-H "Content-Type: application/json" -d '
{
  "municipios": [
    { "nombre": "belgrano", "max": 1, "campos": "id, nombre" },
    { "nombre": "martin", "max": 1, "provincia": "la pampa", "aplanar": true }
  ]
}'

Normalización de direcciones

curl -X POST "https://apis.datos.gob.ar/georef/api/v2.0/direcciones" \
-H "Content-Type: application/json" -d '
{
  "direcciones": [
    { "direccion": "santa fe 3100", "max": 1, "campos": "basico" },
    { "direccion": "corientes 4010", "max": 1, "campos": "basico", "departamento": "General López" }
  ]
}'

Ubicación de entidades geográficas por coordenadas

curl -X POST "https://apis.datos.gob.ar/georef/api/v2.0/ubicacion" \
-H "Content-Type: application/json" -d '
{
  "ubicaciones": [
    { "lat": -27.274161, "lon": -66.752929, "campos": "completo" },
    { "lat": -31.480693, "lon": -59.092813, "aplanar": true, "campos": "completo" }
  ]
}'

Ventajas del uso por lotes

• Reduce la cantidad de llamadas HTTP necesarias.
• Mejora notablemente el rendimiento en escenarios de procesamiento masivo.
• Minimiza el tiempo de respuesta global.
• Ideal para integraciones con sistemas que manejan grandes catálogos de direcciones, municipios, escuelas, etc.