Cliente Python para la API del Servicio de Normalización de Datos Geográficos de Argentina (Georef V2).
Requiere Python 3.7+.
git clone https://github.com/AlenCarbajal/pygeorefar.git
cd pygeorefar
pip install -e .from src.georef_client import GeorefClient
client = GeorefClient()La API es de acceso libre sin autenticación. Para organismos de la Administración Pública Nacional que requieran mayor cuota de uso, la API soporta autenticación mediante JWT. Ver documentación oficial para obtener las credenciales.
client = GeorefClient(jwt_token='tu.token.jwt')Cada endpoint expone un método get_* que acepta un diccionario de parámetros o una instancia de Params y devuelve una lista de instancias del modelo correspondiente.
# Provincias
provincias = client.get_provincias({'max': 5})
# Departamentos de una provincia
departamentos = client.get_departamentos({'provincia': 'Santa Fe', 'max': 10})
# Georreferencia inversa — devuelve una lista con una instancia de Ubicacion
ubicacion = client.get_georef_inversa({'lat': -32.88, 'lon': -60.70})
print(ubicacion[0].provincia.nombre) # "Santa Fe"
# Normalización de direcciones
direcciones = client.get_direcciones({
'direccion': 'Av. Rivadavia 1000',
'provincia': 'Buenos Aires'
})Los métodos post_* reciben una lista de queries y devuelven una lista de listas, una por cada query enviada.
resultados = client.post_provincias([
{'nombre': 'Buenos Aires'},
{'nombre': 'Santa Fe'},
])
# resultados[0] → lista de Provincia para la primera query
# resultados[1] → lista de Provincia para la segunda query
# Georreferencia inversa en lote
ubicaciones = client.post_ubicacion([
{'lat': -32.88, 'lon': -60.70},
{'lat': -34.60, 'lon': -58.43},
])for inicio in range(0, 50, 10):
batch = client.get_departamentos({'inicio': inicio, 'max': 10})| Entidad | GET | POST |
|---|---|---|
| Provincias | get_provincias() |
post_provincias() |
| Departamentos | get_departamentos() |
post_departamentos() |
| Municipios | get_municipios() |
post_municipios() |
| Gobiernos locales | get_gobiernos_locales() |
post_gobiernos_locales() |
| Localidades | get_localidades() |
post_localidades() |
| Localidades censales | get_localidades_censales() |
post_localidades_censales() |
| Asentamientos | get_asentamientos() |
post_asentamientos() |
| Aglomerados | get_aglomerados() |
post_aglomerados() |
| Fracciones censales | get_fracciones_censales() |
post_fracciones_censales() |
| Radios censales | get_radios_censales() |
post_radios_censales() |
| Calles | get_calles() |
post_calles() |
| Direcciones | get_direcciones() |
post_direcciones() |
| Ubicación (georef inversa) | get_georef_inversa() |
post_ubicacion() |
| Establecimientos educativos | get_establecimientos_educativos() |
post_establecimientos_educativos() |
| Instituciones universitarias | get_instituciones_universitarias() |
post_instituciones_universitarias() |
Todos los endpoints GET aceptan los siguientes parámetros base a través de BaseParams:
| Parámetro | Tipo | Descripción |
|---|---|---|
id |
str |
ID de la entidad. Acepta múltiples valores separados por coma. |
nombre |
str |
Nombre de la entidad. Búsqueda parcial por defecto. |
max |
int |
Cantidad máxima de resultados. Máximo: 5000. |
inicio |
int |
Offset para paginación. |
exacto |
bool |
Fuerza coincidencia exacta en búsquedas por nombre. |
orden |
str |
Campo de ordenamiento: id o nombre. |
campos |
str |
Campos a incluir en la respuesta, separados por coma. |
aplanar |
bool |
Aplana objetos anidados en la respuesta. |
formato |
str |
Formato de respuesta: json, geojson, csv o xml. |
Los parámetros enteros (max, inicio) se serializan automáticamente a string antes de enviarse a la API.
Cada endpoint puede tener parámetros adicionales específicos definidos en su clase Params (por ejemplo, provincia, departamento, gestion).
Cada endpoint tiene su modelo Pydantic correspondiente en src/models/. Los campos de los modelos reflejan el schema OpenAPI de la API. Campos que la API no garantiza en todas las respuestas están definidos como Optional.
Modelos con campos completamente opcionales (la API no devuelve id ni nombre para estos recursos):
Ubicacion— resultado de georreferencia inversaFraccionCensal—nombrees opcionalRadioCensal—nombrees opcional
# Unitarios
pytest tests/unit -v
# Integración (requiere conexión a la API)
pytest tests/integration -v -m integration
# Con cobertura
pytest --cov=src tests/MIT