datosgobar / georef-ar-api

API del Servicio de Normalización de Datos Geográficos de Argentina.

georef-ar-api

API del Servicio de Normalización de Datos Geográficos de Argentina.

Documentación

Para consultar la documentación de la API, acceder a https://apis.datos.gob.ar/georef.

Contenedores

Para correr los contenedores asegúrate de tener instalado docker-compose
El archivo de configuración puede correr dos servicios creando los siguientes contenedores:

• georef-api_es01: Un contenedor con Elasticsearch procesar e indexar los datos. Estos datos son almacenados y persistidos en un volumen de docker.
• georef-api_app: Un contenedor con la aplicación. Al correrlo la primera vez es necesario correr una indexación.

Antes de levantar el servicio de la app deberás generar un archivo config/georef.cfg que puedes hacerlo copiando el que ya existe (docker/georef.example.cfg) y renombrando ciertas variables. Tener en cuenta que dentro de la red de docker por defecto el host para el servidor de Elasticsearch es "es01" y el puerto es 9200.
Las carpetas config/; source/; backups/ y logs/ serán montadas dentro del contenedor de georef-api_app y se podrá acceder desde el host a los archivos generados por la app.

El archivo de configuración docker/georef.example.cfg está preparado para ser copiado al destino config/georef.cfg
La fuente de datos está configurada para ser leida desde la carpeta source/; pero si se desea se puede cambiar el archivo georef.cfg para especificar otra ruta o una URL. Si bien se puede copiar los archivos fuente dentro de /source, se recomienda crear un enlace duro; sobre todo si se están haciendo pruebas con el ETL en el mismo entorno de desarrollo.

cp -rl /home/georef-etl/files/latest /home/georef-api/source

Si se encuentra en otra partición se puede optar por un enlace simbólico:

ln /home/georef-etl/files/latest /home/georef-api/source

Para correr la aplicación:

Situarse dentro de la carpeta "docker" y correr el siguiente comando:

docker-compose up -d

Para indexar los archivos generados por el ETL correr el siguiente comando:

docker-compose exec app make index

Nota: Para más comandos referirse a la documentación (https://datosgobar.github.io/georef-ar-api/georef-api-development/#3-crear-los-indices)

El puerto utilizado por la aplicación es el 5000 y se mapea al mismo puerto del host. Ambos valores pueden ser modificados en el archivo docker-compose.yml

Para realizar consultas a la api se puede hacer una petición desde el host a dicho puerto.

Ejemplo:

curl localhost:5000/api/provincias

Nota: Para más endpoints referirse a la documentación (https://datosgobar.github.io/georef-ar-api/open-api/)

Si se modifica el código fuente reconstruir la imagen

docker-compose build app

Soporte

En caso de que encuentres algún bug, tengas problemas con la instalación, o tengas comentarios de alguna parte de Georef API, podés mandarnos un mail a [email protected] o crear un issue.

georef-ar-api's Issues

Modificaciones georef-api

Estimados participe de las charlas de data minning que dio Martin Costa y como miembro del Ministerio Publico Fiscal me interesaria saber si les puedo proponer modificaciones a la api de georeferenciacion ya que tenemos experiencia en el uso de la georeferenciacion y los indices de elasticsearch para las busquedas

Búsqueda de calles/direcciones restringida al índice de provincia específico

Si los parámetros localidad o provincia están presentes en el request, acotar la búsqueda al indice específico en Elasticsearch.

Modificar búsqueda para devolver coordenadas de una dirección según el tramo de calle y su geometría

Tests v1

Armar suite de tests inicial con los casos de uso de la API, y probando casos especiales conocidos del procesamiento de consultas.

Búsqueda con tolerancia a errores en los datos de entrada

Implementar recursos de localidades, departamentos, y provincias

Agregar filtros de tipo de camino, localidad y provincia para el endpoint de calles

Implementación inicial de endpoint GET /normalizador

Especificar formato de respuesta (json o csv)

1. Cuando hay filtros en la consulta, especificar formato a partir del parametro "format". El default es json.
2. Cuando la consulta es sin filtros, se puede especificar el formato tanto mediante el parametro "format" como poniendo ".json" o ".csv" al final. Ejemplo de esto: UK registers -- https://country.register.gov.uk/records.json

Ejemplos:
apis.datos.gob.ar/georef/api/v1.0/provincias.csv
apis.datos.gob.ar/georef/api/v1.0/provincias?nombre=la+pampa&format=csv
apis.datos.gob.ar/georef/api/v1.0/provincias?format=geojson

Procesar tipos de calle usando tabla de abreviaturas de INDEC

• Agregar lógica al módulo parser.py.
• Tests!!!

Actualizar README con info de observaciones, cambios en ejemplos, y nuevos servicios.

Procesar alturas con el esquema de ElasticSearch

Documentar módulos y funciones

Escribir "docstrings" para todos los módulos y funciones de la API según los estándares de código.

Implementar el parser de parámetros de entrada de la API

Modificar las interfaces para que a la capa de búsqueda lleguen todos los parámetros por separado y preprocesados.

Modificar información de altura que se devuelve en los resultados según casos posibles

Usar constantes globales para identificar los nombres de campos que maneja la API.

Mapear tipos de resultado de OSM a conjunto de resultados propios

Tests v1.1

Modificar y extender los casos de prueba en base a los cambios en el diseño de la API.

Modificar resultados de "ubicación" según casos

• Devolver coordenadas si se procesaron correctamente.
• Información extra cuando no se pudo calcular por geometrías inconexa.

Incorporar sinónimos y abreviaturas de cargos, grados, y títulos para nombres de calle

• Agregar lógica al módulo data.py.
• Tests!!!

Manejo de errores en interfaces ElasticSearch y Nominatim

Cambiar niveles de tolerancia de ElasticSearch según cantidad de parámetros de búsqueda

Rearmar indices de ElasticSearch para incluir geometría

Configuración para ambientes local/dev

Observaciones en los resultados de la API (fuente, aclaraciones, etc.)

Autenticación con JSON Web Tokens (v1)

Agregar parámetro para elegir estructura plana en resultados de Localidades y Departamentos

• Habilitar estructuras plana y jerárquica.
• Documentar ejemplos.

Codificación de caracteres especiales en los resultados

Agregar formato geojson hasta Localidad

Tanto en formato csv como formato json, no debería incluirse la geografía de las entidades.

Solamente deberíamos devolver la geografía cuando el usuario pide el formato geojson.

Agregar nuevos filtros de búsqueda a localidades y departamentos.

Extender suite de tests

• Actualizar los casos de prueba.
• Usar mocks para la capa de datos.

API - documentar casos de uso.

Agregar ejemplos de uso al README, mostrando cómo la API puede satisfacer distintos casos con cada recurso.

Integrar datos de OSM para entidades geopolíticas.

Proyección de campos y ordenamiento en los resultados

• Ordenamiento asc y desc según campos (v1 por nombre de entidad del endpoint, orden ascendente).
• Proyectar campos elegidos en el request.
• Elegir entre estructura plana o jerárquica de las entidades (para /localidades y /departamentos).
• Remover geometría de los resultados de calles y direcciones.

Spike de NoSQL - data en documentos

Diseño API - segunda iteración

Modificar documentación de los recursos que se van a exponer, junto con sus ejemplos y modo de uso.

Modificar búsqueda y resultados según parámetros opcionales

• Extender búsqueda a OSM si está el parámetro en la consulta.
• Cantidad de resultados a devolver según parámetro "max".

Georeferenciación Reversa hasta Municipio

Input: Un punto con latitud y longitud
Output: metadata de ese punto -- municipio, localidad (si tiene), departamento y provincia.

Alturas de calle - validar y mostrar en el resultado

Cuando las alturas no existen o la altura está fuera del rango, devolver info de aclaración.

devolución de atributo similar a Accuracy / MatchQuality

Hola!
Sería buenisimo tener un atributo de accurancy tal cual devuelven los servicios de geocode:

ej google:
0 Unknown location.
1 Country level accuracy.
2 Region (state, province, prefecture, etc.) level accuracy.
3 Sub-region (county, municipality, etc.) level accuracy.
4 Town (city, village) level accuracy.
5 Post code (zip code) level accuracy.
6 Street level accuracy.
7 Intersection level accuracy.
8 Address level accuracy.
9 Premise level accuracy from Google Map API v2 doc (enum GGeoAddressAccuracy)

ej here:
https://developer.here.com/documentation/geocoder/topics/resource-type-response-geocode.html
"MatchQuality provides detailed information about the match quality of a result at attribute level. Match quality is a value between 0.0 and 1.0. 1.0 represents a 100% match."

• Country Match quality of the result with respect to country information in the request.
• State Match quality of the result with respect to state information in the request.
• County Match quality of the result with respect to county information in the request.
• City Match quality of the result with respect to city information in the request.
• District Match quality of the result with respect to district information in the request.
• Subdistrict Match quality of the result with respect to sub-district information in the request.
• Street Match quality of the result with respect to street information in the request. There are two values of 'Street' when you specify an intersection.
• HouseNumber Match quality of the result with respect to house number information in the request.
• PostalCode Match quality of the result with respect to postal code information in the request.
• Building Match quality of the result with respect to building information in the request.

Info de errores - modificar estructura en respuestas de la API según pautas del Anexo de Interoperabilidad

Agregar código postal

Sería útil poder tener el código postal de una dirección, ya que actualmente no hay servicios online que provean está información.

Guardar búsquedas con todos los campos relevantes

• Agregar funcionalidad para integrar con la BD operativa para generar registro de eventos.
• Agregar campos faltantes (timestamp, etc.)

Modificar estructura del resultado en POST /normalizador

• Cambiar documentación en el README.
• Cambiar mecanismo que construye el resultado.

Habilitar Travis CI

Documentación mas clara respecto al origen de datos

Hola! buena iniciativa.

Estaría bueno que en el readme esté más claro el origen de datos, es un detalle pero seguramente a todo usuario le interese saber con qué calidad se esta devolviendo esta info (mas que todo relacionada a la altura de calle altura y al código postal 4 / 8 dígitos)

grax!

Extender búsqueda contra la API de Nominatim

Incluir resultados georef en el prototipo en "Comparar servicios"

Implementación inicial del endpoint POST /normalizador

Agregar límite de cantidad resultados a las entidades