GEOCODIFICACIÓN DIRECTA

(EN EDICIÓN)

El método de geocodificación directa, es el proceso que es necesario utilizar para la búsqueda y extracción de datos de una dirección o lugar, junto con las coordenadas geográficas de su ubicación, a partir de sus datos identificativos o de referencia.

La url (endpoint) a la que dirigir la petición es: https://geocoder-5-ign.larioja.org/v1/search


Construcción de la consulta


El formato de interrogación a la API se construye a partir de la url de referencia de este método (/v1/search), seguido del signo ? y de la secuencia de parámetros que configuran la pregunta, separados por el signo &.

Si se desea localizar una dirección que contenga un texto determinado, que es el caso más común, el parámetro a utilizar es text:

Parámetro Tipo Obligatorio Defecto Descripción Ejemplo
text cadena de caracteres ninguno Texto de la dirección a buscar Calle Mayor 10

En el ejemplo siguiente el texto a buscar en la dirección es «murrieta», para lo cual se añade a la url del método de búsqueda https://geocoder-5-ign.larioja.org/v1/search, el signo ? y el parámetro text=murrieta.

https://geocoder-5-ign.larioja.org/v1/search?text=murrieta

Pulsando sobre el enlace anterior se obtiene un fichero en formato GeoJSON que contiene los resultados de la búsqueda que mejor coinciden con el texto «murrieta». El fichero con formato GeoJSON puede ser leído en un navegador web (1) o en un procesador de texto.

En este caso, los resultados obtenidos son los siguientes (2):

BARRIO MURRIETA, Putxeta, Bizkaia, España (-3.091738,43.319819)
CALLE MURRIETA, San Vicente de Barakaldo/San Bizenti-Barakaldo, Bizkaia, España (-2.989928,43.301062)
Calle Marqués de Murrieta, Logroño, La Rioja, España (-2.452761,42.465614)


Configurar el número de resultados


Por defecto la API devuelve hasta 10 resultados. Si se desea un número distinto de resultados, este se puede configurar en la llamada utilizando el parámetro size.

Parámetro Tipo Obligatorio Defecto Descripción Ejemplo
size integer no 10 Número deseado de resultados 5

Si en el ejemplo anterior se deseara recibir solamente un único resultado, la sintaxis de la consulta debería ser:

https://geocoder-5-ign.larioja.org/v1/search?text=murrieta&size=1

siendo el resultado obtenido:

BARRIO MURRIETA, Putxeta, Bizkaia, España (-3.091738,43.319819)


Consulta en un área determinada


Es posible constreñir la búsqueda de direcciones a una región o país en particular, o limitarla a un área específica. La API Pelias que utiliza el geocodificador del SCN permite tres fórmulas para limitar espacialmente la búsqueda: país, rectángulo y círculo.


Búsqueda en un área rectangular


Para limitar la búsqueda a un área geográfica rectangular, es necesario conocer las coordenadas latitud y longitud, mínimas y máximas, que definen el rectángulo (3).

En este caso los parámetros a utilizar son los siguientes:

Parámetro Tipo Obligatorio Defecto Descripción Ejemplo
boundary.rect.max_lat numérico coma flotante no ninguno Valor máximo de la latitud utilizado en la búsqueda en una región rectangular (4) 41.7342
boundary.rect.max_lon numérico coma flotante no ninguno Valor máximo de la longitud utilizado en la búsqueda en una región rectangular (4) -0.6585
boundary.rect.min_lat numérico coma flotante no ninguno Valor mínimo de la latitud utilizado en la búsqueda en una región rectangular (4) 41.5453
boundary.rect.min_lon numérico coma flotante no ninguno Valor mínimo de la longitud utilizado en la búsqueda en una región rectangular (4) -1.1474

Por ejemplo, para encontrar una dirección que contenga el texto "mayor" en el área rectangular que muestra la imagen, definida por las coordenadas lat_min=41.5453; lon_min=-1.1474; at_max=41.7342; lon_max=-0.6585


Rectángulo área de Zaragoza(fuente: visor klokantech.com)

La sintaxis a utilizar es:

https://geocoder-5-ign.larioja.org/v1/search?text=mayor&boundary.rect.min_lat=41.5453&boundary.rect.min_lon=-1.1474&boundary.rect.max_lat=41.7342&boundary.rect.max_lon=-0.6585

siendo estos los resultados obtenidos (2):

CALLE MAYOR, La Muela, Zaragoza, España (1.117274,41.57985)
CALLE MAYOR (MONTAÑANA), MONTAÑANA, Zaragoza, España (-0.822357,41.684245)
CALLE OSA MAYOR, Zaragoza, España (0.932542,41.639184)
PLAZA MAYOR (CARTUJA), Cartuja Baja, Zaragoza, España (-0.821923,41.604933)


Búsqueda en un área circular


En aquellos casos en los que se desea localizar las direcciones que se encuentran dentro de una distancia a un punto dado, se puede utilizar las búsqueda en un área circular, partiendo de una coordenada central de referencia y el radio en km del círculo dentro del cual se quiere realizar la búsqueda.

Los parámetros a utilizar en este caso son los siguientes:

Parámetro Tipo Obligatorio Defecto Descripción Ejemplo
boundary.circle.lat numérico coma flotante no ninguno Valor de la latitud del punto central del círculo utilizado en la búsqueda en una región circular (4) 42.268
boundary.circle.lon numérico coma flotante no ninguno Valor de la longitud del punto central del círculo utilizado en la búsqueda en una región circular (4) -4.405
boundary.circle.radius numérico coma flotante no 50 Valor del radio (kilómetros) utilizado en la búsqueda en una región circular (4) 10

Por ejemplo, para encontrar una dirección que contenga el texto "mayor" en un área circular de 10 km desde Frómista (Palencia), con coordenadas de referencia (lat,lon) 42.268,-4.405.


Círculo 10 km desde Frómista (fuente: propia)

La sintaxis a utilizar es:

https://geocoder-5-ign.larioja.org/v1/search?text=mayor&boundary.circle.lat=42.268&boundary.circle.lon=-4.405&boundary.circle.radius=10

Que arroja el siguiente resultado:

CALLE MAYOR, Marcilla de Campos, Palencia, España (4.397729,42.317378)
PLAZA MAYOR, Santoyo, Palencia, España (-4.34285,42.214136)
TRAVESIA MAYOR, Boadilla del Camino, Palencia, España (-4.347739,42.259541)
TRVA MAYOR, BOADILLA DEL CAMINO, Palencia, España (-4.34823,42.259339)


Búsqueda aplicando jerarquía administrativa


El almacenamiento de información mantiene internamente una estructuración jerárquica entre lugares, aplicando un concepto denominado jerarquía administrativa, en el que cada registro se asocia a un vecindario, ciudad, región, país y otras regiones principales.

Esta propiedad tiene múltiples aplicaciones entre las que destaca el filtrado de información. El ID global de Pelias (gid) de cualquier registro se puede usar con el filtro boundary.gid para devolver solo registros con un ascendente determinado.

Si se definen varios tipos de regiones en la misma solicitud, los resultados corresponderán a la intersección de todos los límites. Por lo que si las regiones no se superponen, el resultado de la consulta no contendrá datos.

Por el momento no se ha implementado el gid en las tablas de regiones, por lo que parámetro boundary.gid no genera resultados específicos.


Priorización de resultados por proximidad


En algunas ocasiones es conveniente presentar los resultados más cercanos a una ubicación o región en la parte superior de la lista sin renunciar a otros resultados que se encuentran geográficamente más lejanos.

La geolocalización directa permite priorizar los resultados dentro de los límites geográficos, incluso alrededor de un punto, dentro de un país o dentro de una región.


Priorizar la proximidad a un punto


Aplicando a la búsqueda el parámetro focus.point, los resultados se ordenarán en parte por su proximidad a la coordenada dada.

Para las mismas condiciones, los resultados más cercanos al punto aparecerán en la parte superior de la relación. Sin embargo, a diferencia de las consultas circunscritas a áreas rectangulares o circulares, este parámetro puede devolver resultados muy distantes de la coordenada de referencia.

Los parámetros a utilizar para la consulta por proximidad a un punto son:

Parámetro Tipo Obligatorio Defecto Descripción Ejemplo
focus.point.lat numérico coma flotante no ninguno Valor de la latitud utilizado en la búsqueda alrededor de un punto (4) 42.268
focus.point.lon numérico coma flotante no ninguno Valor de la longitud utilizado en la búsqueda alrededor de un punto (4) -4.405

Si repetimos la consulta de ejemplo utilizada en la busqueda por círculo, pero en este caso utilizando las coordenadas de Frómista para consultar por proximidad a un punto:

https://geocoder-5-ign.larioja.org/v1/search?text=mayor&focus.point.lat=42.268&focus.point.lon=-4.405

Se obtiene el siguiente resultado:

CALLE MAYOR, Población de Campos, Palencia, España"(-4.448308,42.270092) [distancia: 3.575]
TRVA MAYOR, BOADILLA DEL CAMINO, Palencia, España (-4.34823,42.259339) [distancia: 4.775]
TRAVESIA MAYOR, Boadilla del Camino, Palencia, España (-4.347739,42.259541) [distancia: 4.810]
PLAZA MAYOR, BOADILLA DEL CAMINO, Palencia, España (4.347215,42.259306) [distancia: 4.858]


Búsqueda combinada priorizada dentro de un área


Es posible combinar en la misma consulta la búsqueda en un área determinada, ordenando al mismo tiempo los resultados por su proximidad a un punto dado.

En el siguiente ejemplo se prioriza la búsqueda en un área rectangular en las proximidades de Zaragoza, priorizando la proximidad a su esquina de coordenadas latitud,longitud mínimas:

https://geocoder-5-ign.larioja.org/v1/search?text=mayor&boundary.rect.min_lat=41.5453&boundary.rect.min_lon=-1.1474&boundary.rect.max_lat=41.7342&boundary.rect.max_lon=-0.6585&focus.point.lat=41.5453&focus.point.lon=-1.1474

El resultado obtenido por orden de priorización es:

CALLE MAYOR, La Muela, Zaragoza, España (1.122955,41.577862) [distancia: 4.158]
CALLE MAYOR (GARRAPINILLOS), Garrapinillos, Zaragoza, España (1.028693,41.682992) [distancia: 18.236]
CALLE OSA MAYOR, ZARAGOZA, España (-0.932936,41.637167) [distancia": 20.577]


Filtrado de la búsqueda



Filtrado por origen de los datos


El almacén de datos de referencia en este geocodificador permite combinar datos procedentes de distintas fuentes, de hecho, uno de los objetivos principales del proyecto es definir un modelo de datos neutro en formato CSV, con objeto de poder cargar datos provenientes de distintos productores.

La API Pelias ofrece la posibilidad de seleccionar, entre todos, el conjunto de datos de referencia al cual dirigir la búsqueda.

En la fase de pruebas se han cargado direcciones de las siguientes fuentes de datos (5).

Cuando se realiza una consulta, se dirige por defecto al conjunto de todas las direcciones que están almacenadas en la base de datos.

Utilizando el parámetro sources, es posible definir sobre qué conjuntos de datos realizar la petición.

Parámetro Tipo Obligatorio Defecto Descripción Ejemplo
sources cadena de caracteres no todas las fuentes Listado de fuentes de datos separados por comas, codificados según lista controlada Proveedores de datos cnig,calrj

El siguiente ejemplo realiza una consulta general a toda la base de datos:

https://geocoder-5-ign.larioja.org/v1/search?text=mayor 10 Briones

En tanto que el siguiente ejemplo dirige la consulta solamente a los datos aportados por el Gobierno de La Rioja:

https://geocoder-5-ign.larioja.org/v1/search?text=mayor 10 Briones&sources=calrj


Filtrado por tipo de datos


El almacenamiento de datos se realiza en tablas diferentes en función de su naturaleza, lo que permite diferenciar tres tipología de datos: direcciones; topónimos y puntos de interés (POIs).

El parámetro layers permite dirigir la petición de información a las siguientes capas, con el fin de obtener el resultado deseado:

layer (capa) descripción
venue topónimos; puntos de interés; nombres propios de las direcciones
address puntos con una dirección postal
street calles; vías; carreteras

El uso del parámetro layers es el siguiente:

Parámetro Tipo Obligatorio Defecto Descripción Ejemplo
layers cadena de caracteres no todas las capas Nombres de las capas de datos a las que se dirije la consulta, separados por comas venue, street

Ejemplos:

Búsqueda del topónimo Mirador del Moro: https://geocoder-5-ign.larioja.org/v1/search?text=Mirador del Moro&layers=venue


Mirador del Moro(fuente: imagen propia)


Búsqueda del punto de interés Cortijo Majón: https://geocoder-5-ign.larioja.org/v1/search?text=Cortijo Majón&layers=venue


Cortijo Majón(fuente: imagen propia)


Cuadro de parámetros


Esta es la relación de parámetros que se pueden utilizar en las operaciones de geocodificación directa:

Parámetro Tipo Obligatorio Defecto Descripción Ejemplo
boundary.circle.lat numérico coma flotante no ninguno Valor de la latitud del punto central del círculo utilizado en la búsqueda en una región circular (4) 42.268
boundary.circle.lon numérico coma flotante no ninguno Valor de la longitud del punto central del círculo utilizado en la búsqueda en una región circular (4) -4.405
boundary.circle.radius numérico coma flotante no 50 Valor del radio (kilómetros) utilizado en la búsqueda en una región circular (4) 10
boundary.country cadena de caracteres no ninguno

NO IMPLEMENTADO

boundary.gid cadena de caracteres no ninguno

NO IMPLEMENTADO

boundary.rect.max_lat numérico coma flotante no ninguno Valor máximo de la latitud utilizado en la búsqueda en una región rectangular (4) 41.7342
boundary.rect.max_lon numérico coma flotante no ninguno Valor máximo de la longitud utilizado en la búsqueda en una región rectangular (4) -0.6585
boundary.rect.min_lat numérico coma flotante no ninguno Valor mínimo de la latitud utilizado en la búsqueda en una región rectangular (4) 41.5453
boundary.rect.min_lon numérico coma flotante no ninguno Valor mínimo de la longitud utilizado en la búsqueda en una región rectangular (4) -1.1474
focus.point.lat numérico coma flotante no ninguno Valor de la latitud utilizado en la búsqueda alrededor de un punto (4) 42.268
focus.point.lon numérico coma flotante no ninguno Valor de la longitud utilizado en la búsqueda alrededor de un punto (4) -4.405
layers cadena de caracteres no todas las capas Nombres de las capas de datos a las que se dirije la consulta, separados por comas venue, street
size integer no 10 Número deseado de resultados 5
sources cadena de caracteres no todas las fuentes Listado de fuentes de datos separados por comas, codificados según lista controlada Proveedores de datos cnig,calrj
text cadena de caracteres ninguno Texto de la dirección a buscar Calle Mayor 10



NOTAS:
(1) Se aconseja implementar en el navegador web un complemento para la visualización estructurada de ficheros JSON.
(2) Aunque las coordenadas geográficas generalmente se suelen expresar en el orden latitud,longitud, los resultados de la API se ofrecen en el orden longitud,latitud.
(3) Puede obtener las coordenadas de un rectángulo geográfico mediante la utilidad web de Klokantech.
(4) Utilizar la notación punto (.) como signo de separación decimal.
(5) A los datos de direcciones que se encuentran en desuso o sin vigencia administrativa, cuyo atributo ESTADO tiene el valor Histórico, se les añade al código de proveedor el sufijo «-h», con objeto de poder realizar *geocodificación directa* específica mediante el parámetro sources, y evitar al mismo tiempo interferencias en los procesos de geocodificación inversa.