Servicio API de geocodificación de direcciones
El Servicio API de geocodificación de direcciones del Gobierno de La Rioja, tiene como objetivo principal buscar y obtener la localización geográfica de cualquier dirección que se encuentre ubicada en el territorio de la Comunidad Autónoma de La Rioja a partir de sus datos identificativos, .
La URL del servicio es: https://geocoder.larioja.org/v1/
Además de la geolocalización de una dirección concreta, este servicio permite obtener los datos de las direcciones cercanas a un punto determinado, así como aquellas que están ubicadas dentro de un área geográfica rectangular o circular determinada.
Los métodos (endpoints) y parámetros que se describen aquí, permiten a cualquier usuario identificar y localizar direcciones con la máxima precisión a partir de los datos completos o parciales que definen una referencia postal, de un identificador o número de registro, o de un nombre representativo de la misma.
Los datos básicos de las direcciones de referencia son recopilados a partir de la información proporcionada por los diferentes ayuntamientos de La Rioja, dentro del marco de cooperación que ofrece la Infraestructura de Datos Espaciales de La Rioja (IDErioja) .
Además de direcciones, el servicio de geocodificación está también diseñado para la localización geográfica de topónimos y puntos de interés (POI).
Funcionalidad
Las características técnicas que cumple el servicio son las siguientes:
- Operaciones de descubrimiento y geolocalización (obtención de coordenadas geográficas) de una dirección en base a sus principales componentes (población, nombre del vial, portal, etc.).
- Priorización de las soluciones más cercanas geográficamente a un punto dado.
- Operaciones de geocodificación inversa para el descubrimiento de la dirección más próxima a un punto de coordenadas conocidas.
- Búsqueda circunscrita dentro de un área geográfica o una unidad administrativa determinada.
- Búsqueda selectiva en subconjuntos de datos de uno o varios proveedores de datos.
- Búsqueda selectiva en subconjuntos de datos según tipo y estado del dato.
- Tecnología API REST (Interfaz de Programación de Aplicaciones). Posibilidad de poder invocar los métodos y procedimientos desde aplicaciones y procesos informáticos.
En cuanto a la funcionalidad, el servicio permite:
- Localización de direcciones fuera del ámbito urbano
- Localización de direcciones en vigor e históricas (en desuso).
- Consulta de direcciones expresadas en cualquiera de las lenguas oficiales.
- Utilización de sinónimos y abreviaturas.
- Respuesta a búsqueda de direcciones no estructuradas.
- Búsqueda de una dirección a partir de su nombre propio.
- Geolocalización de toponimia y nombres geográficos.
- Geolocalización de puntos de interés (POI).
La API de direcciones
La API utilizada en este servicio, es una API RESTful que devuelve el resultado de las consultas realizadas en formato JSON , conforme a los métodos y parámetros definidos en este documento.
Métodos
Geocodificación directa:
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, topónimo o POI, 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.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
(https://geocoder.larioja.org/v1/search), seguido del signo
?
y de la secuencia de parámetros que configuran la pregunta, separados estos por el signo
&
.
Si se desea localizar una dirección, topónimo o POI 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 | sí | ninguno | Texto de la dirección a buscar | Calle Mayor 10 |
En el ejemplo siguiente el texto a buscar en la dirección es «carnicerías», para lo cual se añade a la url del método de búsqueda
https://geocoder.larioja.org/v1/search
, el signo
?
y el parámetro
text=carnicerías.
https://geocoder.larioja.org/v1/search?text=carnicerías
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 «carnicerías». El fichero con formato GeoJSON puede ser leído en un navegador web (1) o en un procesador de textos.
En este caso, los resultados obtenidos son los siguientes (2) :
TRAVESÍA CARNICERÍAS, Ausejo, La Rioja, España (-2.17064,42.34409)
CALLE CARNICERÍAS, Ausejo, La Rioja, España (-2.17054,42.34465)
TRAVESÍA CARNICERÍAS, San Millán de la Cogolla, La Rioja, España (-2.861,42.3302)
CALLE CARNICERÍAS, Cuzcurrita de Río Tirón, La Rioja, España (-2.9651,42.54251)
CALLE CARNICERÍAS, Cornago, La Rioja, España (-2.09479,42.06481)
CALLEJÓN CARNICERÍAS, Cornago, La Rioja, España (-2.09421,42.06522)
CALLE CARNICERÍAS, Ezcaray, La Rioja, España (-3.0157,42.3242)
CALLE CARNICERÍAS, Lardero, La Rioja, España (-2.46253,42.42814)
CALLE CARNICERÍAS, Logroño, La Rioja, España (-2.4464,42.46693)
CALLEJÓN CARNICERÍAS, Azofra, La Rioja, España (-2.8012,42.42344)
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.larioja.org/v1/search?text=carnicerías&size=1
siendo este el resultado obtenido:
TRAVESÍA CARNICERÍAS, Ausejo, La Rioja, España (-2.17064,42.34409)
Consulta en un área determinada
Es posible delimitar la búsqueda de direcciones a una región o país en particular, o limitarla a un área específica. La API que utiliza el geocodificador del Gobierno de La Rioja ofrece tres fórmulas para limitar espacialmente la búsqueda: rectángulo, círculo y país.
Búsqueda en un área rectangular
Para limitar la búsqueda a un área geográfica rectangular, es necesario conocer previamente 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) | 42.4732824 |
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) | -2.3676873 |
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) | 42.4205850 |
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) | -2.4811247 |
Por ejemplo, para encontrar una dirección que contenga el texto «donantes» en el área rectangular que muestra la imagen, definida por las coordenadas lat_min=42.4205850; lon_min=-2.4811247; lat_max=42.4732824; lon_max=-2.3676873.
La sintaxis a utilizar es:
siendo estos los resultados obtenidos:
CALLE DONANTES DE SANGRE, Logroño, La Rioja, España (-2.43118,42.46302)
CALLE DONANTES DE SANGRE, Lardero, La Rioja, España (-2.45792,42.42886)
CALLE DONANTES DE SANGRE, Villamediana de Iregua, La Rioja, España (-2.41669,42.43006)
Búsqueda en un área circular
En el aquellos casos en los que se desea localizar las direcciones que se encuentran dentro de una distancia a un punto dado, se puede utilizar la búsqueda en un área circular, señalando 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 un área circular (4) | 42.46456 |
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 un área circular (4) | -2.44660 |
boundary.circle.radius
|
numérico coma flotante | no | 50 | Valor del radio (kilómetros) utilizado en la búsqueda en un área circular (4) | 10 |
Por ejemplo, para encontrar una dirección que contenga el texto «mayor» en un área circular de 10 km desde Logroño (La Rioja), con coordenadas de referencia (lat,lon) 42.464560,-2.446600.
La sintaxis a utilizar es:
Que arroja el siguiente resultado:
CALLE MAYOR, Logroño, La Rioja, España (-2.4426,42.46836)
CALLE MAYOR, Alberite, La Rioja, España (-2.42766,42.40385)
CALLE MAYOR, Fuenmayor, La Rioja, España (-2.55909,42.46724)
CALLE MAYOR ALTA, Fuenmayor, La Rioja, España (-2.5599,42.46709)
CALLE SANCHO EL MAYOR, Logroño, La Rioja, España (-2.46213,42.45926)
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 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.46456 |
focus.point.lon
|
numérico coma flotante | no | ninguno | Valor de la longitud utilizado en la búsqueda alrededor de un punto (4) | -2.44660 |
Si repetimos la consulta de ejemplo utilizada en la busqueda por círculo, pero en este caso utilizando las coordenadas de Logroño para consultar por proximidad a un punto:
https://geocoder.larioja.org/v1/search?text=mayor&focus.point.lat=42.46456&focus.point.lon=-2.44660
Se obtiene el siguiente resultado:
CALLE MAYOR, Logroño, La Rioja, España (-2.4426,42.46836) [distancia: 0.536]
CALLE MAYOR, Alberite, La Rioja, España (-2.42766,42.40385) [distancia: 6.935]
PLAZA MAYOR, Navarrete, La Rioja, España (-2.56112,42.42946) [distancia: 10.186]
CALLE MAYOR, Entrena, La Rioja, España (-2.53035,42.38758) [distancia: 10.991]
CALLE MAYOR, Murillo de Río Leza, La Rioja, España (-2.32541,42.40358) [distancia: 12.051]
PLAZA MAYOR, Albelda de Iregua, La Rioja, España (-2.47447,42.35764) [distancia: 12.121]
CALLE MAYOR, Albelda de Iregua, La Rioja, España (-2.47249,42.35724) [distancia: 12.135]
CALLE MAYOR, Murillo de Río Leza, La Rioja, España (-2.3244,42.39899) [distancia: 12.413]
PLAZA MAYOR, Medrano, La Rioja, España (-2.554,42.38268) [distancia: 12.687]
CALLE MAYOR, Ribafrecha, La Rioja, España (-2.38756,42.35557) [distancia: 13.067]
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 Logroño, priorizando la proximidad a su esquina de coordenadas latitud,longitud mínimas:
El resultado obtenido por orden de priorización es:
PLAZA MAYOR, Albelda de Iregua, La Rioja, España (-2.47447,42.35764) [distancia: 1.813]
CALLE MAYOR, Albelda de Iregua, La Rioja, España (-2.47249,42.35724) [distancia: 1.873]
CALLE MAYOR, Alberite, La Rioja, España (-2.42766,42.40385) [distancia: 8.236]
CALLE MAYOR, Ribafrecha, La Rioja, España (-2.38756,42.35557) [distancia: 8.255]
CALLE MAYOR, Logroño, La Rioja, España (-2.4426,42.46836) [distancia: 14.301]
CALLE SANCHO EL MAYOR, Logroño, La Rioja, España (-2.46213,42.45926) [distancia: 12.98]
Filtrado de la búsqueda
Filtrado por origen de los datos
El almacén de datos de referencia del geocodificador del Gobierno de La Rioja permite combinar datos procedentes de distintas fuentes de datos (5) .
La API ofrece la posibilidad de seleccionar, entre todos, el conjunto de datos de referencia al cual dirigir la búsqueda.
Cuando se realiza una consulta, esta 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 los conjuntos de datos a los que dirigir 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 | calrj, mun26132 |
El siguiente ejemplo realiza una consulta general a toda la base de datos:
https://geocoder.larioja.org/v1/search?text=doctor 10
En tanto que el siguiente ejemplo dirige la consulta solamente a los datos aportados por la Comunidad Autónoma de La Rioja:
https://geocoder.larioja.org/v1/search?text=doctor 10&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 tipos de datos: dirección (address) ; calle (street) y lugar (venue).
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 |
Cuando en el texto de la búsqueda se indica el texto de la calle pero no un número específico, la API interpreta que se está intentando localizar elementos del tipo «street». Si en estos casos se quiere forzar la respuesta para que devuelva datos de direcciones y no de calles, es imprescindible configurar la pregunta añadiendo el parámetro «layers=address».
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, address, street |
El siguiente ejemplo realiza la búsqueda del punto de interés Oficina de La Rioja en Bruselas:
https://geocoder.larioja.org/v1/search?text=Oficina de La Rioja en Bruselas&layers=venue
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.46456 |
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) | -2.44660 |
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) | 42.4732824 |
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) | -2.3676873 |
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) | 42.4205850 |
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) | -2.4811247 |
focus.point.lat
|
numérico coma flotante | no | ninguno | Valor de la latitud utilizado en la búsqueda alrededor de un punto (4) | 42.46456 |
focus.point.lon
|
numérico coma flotante | no | ninguno | Valor de la longitud utilizado en la búsqueda alrededor de un punto (4) | -2.44660 |
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, address, 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 | calrj, mun26132 |
text
|
cadena de caracteres | sí | ninguno | Texto de la dirección a buscar | Calle Mayor 10 |
Geocodificación inversa:
La geocodificación inversa, es el método utilizado para encontrar las direcciones, topónimos o puntos de interés que se encuentran más próximos a un punto de coordenadas dadas.
La url (endpoint) a la que dirigir las peticiones de
geocodificación inversa
es:
https://geocoder.larioja.org/v1/reverse
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
(https://geocoder.larioja.org/v1/reverse), seguido del signo
?
y de la secuencia de parámetros que configuran la pregunta, separados estos por el signo
&
.
Para realizar una codificación inversa es necesario disponer siempre de las coordenadas del punto cerca del cual se quiere localizar la información, especificando su latitud y longitud en la llamada mediante los parámetros
point.lat
y
point.lon
respectivamente.
Ejemplo: Se desea localizar el punto, dirección, topónimo o POI, más próximo a la dirección Paseo Príncipe de Vergara de Logroño (conocida como Paseo del Espolón) con coordenadas de referencia (lat,lon) 42.464600,-2.444580.
La sintaxis a utilizar es: https://geocoder.larioja.org/v1/reverse?point.lat=42.464600&point.lon=-2.444580
Pulsando sobre el enlace anterior se obtiene un fichero en formato GeoJSON que contiene los resultados de la búsqueda de los puntos más próximos a la ubicación dada, en este ejemplo el Paseo Príncipe de Vergara en Logroño.
El fichero con formato GeoJSON puede ser leído en un navegador web (6) o en un procesador de texto.
Cuadro de parámetros
Como en otros métodos, las operaciones de consulta de geocodificación inversa se pueden configurar añadiendo a la sintaxis de la pregunta distintos parámetros, que en este caso son los siguientes:
| Parámetro | Tipo | Obligatorio | Defecto | Descripción | Ejemplo |
|---|---|---|---|---|---|
boundary.circle.radius
|
numérico coma flotante | no | 50 | Valor del radio (kilómetros) utilizado en la búsqueda en una región circular (6) | 10 |
boundary.country
|
cadena de caracteres | no | ninguno |
NO IMPLEMENTADO |
|
boundary.gid
|
cadena de caracteres | no | ninguno |
NO IMPLEMENTADO |
|
point.lat
|
numérico coma flotante | no | ninguno | Valor de la latitud del punto de referencia utilizado en la geocodificación inversa (6) | 42.464600 |
point.lon
|
numérico coma flotante | no | ninguno | Valor de la longitud del punto de referencia utilizado en la geocodificación inversa (6) | -2.444580 |
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, address, 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 | calrj, mun26132 |
Configuración de la consulta
Los parámetros relacionados en el cuadro anterior permiten configurar distintos aspectos de la consulta.
Fijar 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.larioja.org/v1/reverse?point.lat=42.464600&point.lon=-2.444580&size=1
El valor por defecto del parámetro
size
es 10, pudiéndose configurar la respuestas hasta un máximo de 40 resultados. Si se sobrepasa este valor, la respuesta devolverá 40 resultados junto a un mensaje de advertencia.
Filtrado por origen de los datos
El almacén de datos de referencia del geocodificador IDERioja puede contener información procedente de las siguientes fuentes de datos (7) .
La
geocodificación inversa
devuelve por defecto resultados de cualquiera de las fuentes de datos disponibles, pero utilizando el parámetro
sources
, es posible constreñir la búsqueda a los datos de un proveedor en particular a bien un conjunto de ellos.
| Parámetro | Tipo | Obligatorio | Defecto | Descripción | Ejemplo |
|---|---|---|---|---|---|
sources
|
cadena de caracteres | no | todas las fuentes | Listado de fuentes de datos separados por comas | calrj, mun26132 |
El siguiente ejemplo dirige la consulta a los puntos más cercanos a la ubicación conocida como Glorieta del Doctor Zubía, mostrando solamente los datos aportados por la Comunidad Autónoma de La Rioja:
https://geocoder.larioja.org/v1/reverse?point.lat=42.465486&point.lon=-2.442736&sources=calrj
En la siguiente imagen se puede ver mapeado el fichero GeoJSON con los resultados de la petición.
Filtrado por tipo de datos
El geocoder del Gobierno de La Rioja almacena la información puntual de tres tipos de datos: dirección (address), calle (street) y lugar (venue).
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 |
Cuando en el texto de la búsqueda se indica el texto de la calle pero no un número específico, la API interpreta que se está intentando localizar elementos del tipo «street». Si en estos casos se quiere forzar la respuesta para que devuelva datos de direcciones y no de calles, es imprescindible configurar la pregunta añadiendo el parámetro «layers=address».
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 dirige la consulta, separados por comas | venue, address, street |
El siguiente ejemplo realiza la búsqueda de calles o vías cercanas al
Paseo Príncipe de Vergara:
https://geocoder.larioja.org/v1/reverse?point.lat=42.464600&point.lon=-2.444580&layers=street
La imagen siguiente muestra el mapeado del fichero GeoJSON que contiene los resultados de la petición.
Distancia y valor de confianza
En la geocodificación inversa el fichero GeoJSON contiene para cada elemento devuelto la información de la distancia de este al punto de referencia, junto con una puntuación que valora el nivel de confianza de la respuesta.
Los valores de confianza se calculan en función de la distancia desde el resultado hasta el punto de referencia establecido, siendo probable que este valor calculado cambie con diferentes fuentes y capas de datos.
| Distancia desde el punto de referencia | Valor de confianza |
|---|---|
| < 1m | 1.0 |
| < 10m | 0.9 |
| < 100m | 0.8 |
| < 250m | 0.7 |
| < 1km | 0.6 |
| >= 1km | 0.5 |
Autocompletar
Las aplicaciones de localización de direcciones suelen incorporar una funcionalidad de búsqueda al vuelo de direcciones, calles, topónimos o puntos de interés a partir del texto que el usuario va introduciendo, anticipando un conjunto de posibles resultados con objeto de seleccionar uno de ellos.
En el caso de la
API de geocodificación IDErioja
la url que responde al método
autocompletar
es:
https://geocoder.larioja.org/v1/autocomplete
Mediante este método no es necesario lanzar una petición de geocodificicación directa especificando de forma completa todos los términos de la búsqueda.
El autocompletado requiere interrogar sucesivamente a la url (endpoint) de este método
(https://geocoder.larioja.org/v1/autocomplete), pasándole el texto que el usuario va escribiendo a medida que lo teclea. Las peticiones pueden ir acompañadas de un
focus.point
con objeto de priorizar los resultados cercanos a un punto dado.
Cuadro de parámetros
La relación de parámetros que se pueden utilizar en las operaciones de autocompletar es la siguiente:
| 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.46456 |
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) | -2.44660 |
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) | 42.4732824 |
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) | -2.3676873 |
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) | 42.4205850 |
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) | -2.4811247 |
focus.point.lat
|
numérico coma flotante | no | ninguno | Valor de la latitud utilizado en la búsqueda alrededor de un punto (4) | 42.46456 |
focus.point.lon
|
numérico coma flotante | no | ninguno | Valor de la longitud utilizado en la búsqueda alrededor de un punto (4) | -2.44660 |
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, address, 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 | calrj, mun26132 |
text
|
cadena de caracteres | sí | ninguno | Texto de la dirección a buscar | Calle Mayor 10 |
Implementación
Para la implementeción de la función autocompletar es conveniente tener en cuenta las siguientes recomendaciones:
Limitación de las solicitudes
Dado que las solicitudes de autocompletar generalmente responden directamente a la entrada de texto que realiza el usuario, es importante tener en cuenta la velocidad de escritura con objeto de no colapsar las peticiones ya que algunos dispositivos y redes pueden no responder correctamente cuando se envían demasiadas solicitudes demasiado rápido, por lo que es conveniente realizar antes algunas pruebas para acotar la cadencia y el número de las peticiones.
La experiencia recomienda realizar entre 5 y 10 solicitudes por segundo, ya que este rango es el que ofrece el mejor equilibrio entre el uso de recursos y la capacidad de respuesta de autocompletar. En este sentido es recomendable configurar un regulardor en el lado del cliente con objeto de evitar exceder esos límites. Es aconsejable enviar menos solicitudes, en sus propios términos, que confiar en la limitación de velocidad del servidor para decidir qué solicitudes recibirán una respuesta completa.
Respuestas asíncronas
También es necesario tener en cuenta que las respuestas del servicio pueden ser asíncronas y no ser devueltas en el mismo orden en el que fueron realizadas.
Como las peticiones se realizan a medida que el usuario escribe, pueden generarse peticiones parciales para una cadena de texto, siendo asíncronas las respuestas recibidas.
Imagine que las pulsaciones de teclado de un usuario que introduce el texto de búsqueda «logroño» genera dos peticiones síncronas: la primera con el texto «lo» y la segunda con el texto «logroño». En este caso es posible que el usuario reciba antes la respuesta a la petición «logroño» que a la petición «lo», ya que las solicitudes de autocompletar con más caracteres probablemente se resolverán más rápido puesto que el espacio de búsqueda de la consulta es más reducido.
Es necesario tener en cuenta que la recepción de respuestas asíncronas puede generar cierta confusión en los usuarios.
Uso de la geocodificación directa
Se recomientda utilizar la geocodificación directa incluso con autocompletar.
Si bien el método autocompletar está diseñado específicamente para su uso con entradas introducidas por el usuario, considere la posibilidad de utilizar la geocodificación directa en ciertas situaciones.
Una forma común de utilización es enviar una solicitud
autocompletar
al presionar una tecla
(limitando las peticiones como se comentó anteriormente), y enviar una solicitud de
geocodificación directa
cuando el usuario presiona la tecla
Intro
o un botón de envío sobre una de las soluciones ofrecidas por
autocompletar.
Este enfoque permite utilizar la velocidad y el manejo de entrada parcial del método autocompletar cuando sea necesario, y la precisión y funcionalidad adicional de la geocodificación directa cuando sea posible.
El buscador de direcciones IDErioja es un ejemplo de diseño que implementa esta estrategia. Cuando el usuario empieza a escribir los datos de una dirección, se realizan automáticamente peticiones utilizando el método autocompletar (autocomplete) que permite ir consultando una oferta de posibles soluciones, pero cuando el usuario pulsa la tecla [INTRO] se genera una petición a la API utilizando el método de geocodificación directa (search).
Uso de librerías prediseñadas
Si tiene posibilidad, utilice una librería cliente que incorpore internamente las pautas de uso del método autocompletar.
Si utiliza Leaflet, puede valorar el uso del plugin Nextzen (anteriormente Mapzen). Este plugin ofrece todas las pautas de autocompletar descritas aquí.
Configurar el número de resultados
Como en otros métodos, la API devuelve por defecto hasta 10 resultados. Si se quiere recibir un número distinto de resultados, es posible configurar el número deseado 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 |
Ejemplo de configuración de autocompletar que ofrece una relación de 15 resultados posibles en respuesta al envío de la cadena de texto «antoni».
https://geocoder.larioja.org/v1/autocomplete?text=antoni&size=15
Enfoque local
Para priorizar la búsqueda en un área geográfica específica, como el centro del mapa del usuario o la ubicación GPS del dispositivo, se pueden utilizar los parámetros
focus.point.lat
y
focus.point.lon. Esto aumenta los resultados relevantes a nivel local.
| 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.46456 |
focus.point.lon
|
numérico coma flotante | no | ninguno | Valor de la longitud utilizado en la búsqueda alrededor de un punto (4) | -2.44660 |
Por ejemplo, si se quiere centrar la petición de autocompletado del ejemplo anterior, texto=«antoni», en la ciudad de Logroño, de coordenadas de referencia latitud,longitud: 42.46456,-2.44660, la sintaxis (4) a emplear es:
que ofrece los siguientes 10 resultados :
CALLE ANTONIO SAGASTUY, Logroño, La Rioja, España (-2.45189,42.46648)
PARQUE SAN ANTONIO, Logroño, La Rioja, España (-2.4434,42.47121)
CALLE ANTONIO DE NEBRIJA, Logroño, La Rioja, España (-2.43115,42.45503)
CALLE ANTONIO PALACIO VALDÉS Lardero La Rioja España (-2.45891,42.42962)
CALLE ANTONIO ESTEBAN, Lardero, La Rioja, España (-2.45961,42.42788)
CALLE ANTONIO MACHADO, Villamediana de Iregua, La Rioja, España (-2.42239,42.4232)
CALLE PARALELA SAN ANTONIO, Navarrete, La Rioja, España (-2.5634,42.4323)
TRAVESÍA SAN ANTONIO, Navarrete, La Rioja, España (-2.5632,42.43137)
CALLE TRASERA SAN ANTONIO, Navarrete, La Rioja, España (-2.5635,42.43139)
CALLEJA SAN ANTONIO, Navarrete, La Rioja, España (-2.56344,42.4311)
Obsérvese que como no se ha especificado en la petición ninguna capa en particular, los resultados obtenidos deberían corresponder a las tres capas posibles: venue, address y street, solo que en este caso por tratarse de una petición muy genérica en la que no se especifica ninguna numeración, el servidor prescinde de los resultados de la capa address para optimizar el tiempo de respuesta. "warnings": ["performance optimization: excluding 'address' layer"]
Si se quiere realizar la misma petición centrando los resultados en la ciudad de Calahorra de coordenadas de referencia latitud,longitud: 42.3015,-1.9612, la sintaxis a emplear en este caso es:
CALLE ANTONIO MACHADO, Calahorra, La Rioja, España (-1.97176,42.30551)
CALLE SAN ANTONIO, Pradejón, La Rioja, España (-2.06861,42.33497)
CALLE ANTONIO MACHADO, Aldeanueva de Ebro, La Rioja, España (-1.89146,42.22592)
CALLE JUAN ANTONIO LLORENTE, Rincón de Soto, La Rioja, España (-1.85816,42.23313)
CALLE SAN ANTONIO, Arnedo, La Rioja, España (-2.09941,42.22901)
CALLE ANTONIO MACHADO, Arnedo, La Rioja, España (-2.09957,42.22679)
CALLE DEL TORERO ANTONIO LEÓN, Arnedo, La Rioja, España (-2.10631,42.22121)
GRUPO JOSÉ ANTONIO PÉREZ OTAÑO, Arnedo, La Rioja, España (-2.10993,42.2232)
CALLE ANTONIO MIRALLES, Arnedo, La Rioja, España (-2.1131,42.22294)
AVENIDA DE JOSÉ ANTONIO, Alfaro, La Rioja, España (-1.75399,42.179)
El método autocompletar puede promover los resultados cercanos a la parte superior de la lista, al mismo tiempo que permite que las coincidencias importantes más lejanas sean visibles. Por ejemplo, buscando una calle que contenga la palabra «Llorente» con un enfoque en la población de Navarrete (La Rioja):
Si se realiza la petición autocompletar sin especificar ningún enfoque:
https://geocoder.larioja.org/v1/autocomplete?text=llorente
CALLE FRANCISCO LLORENTE, Rincón de Soto, La Rioja, España (-1.85133,42.23428)
CALLE SAN LLORENTE, Navarrete, La Rioja, España (-2.56748,42.42996)
PARQUE CARMEN RIVAS LLORENTE, Logroño, La Rioja, España (-2.43826,42.45435)
CALLE JUAN ANTONIO LLORENTE, Rincón de Soto, La Rioja, España (-1.85816,42.23313)
Si centramos la pregunta en el entorno de la población de Navarrete (La Rioja) de coordenadas de referencia latitud,longitud: 42.23428,-1.85133443, el orden de las respuestas prioriza la más cercana al punto especificado:
CALLE SAN LLORENTE, Navarrete, La Rioja, España (-2.56748,42.42996)
PARQUE CARMEN RIVAS LLORENTE, Logroño, La Rioja, España (-2.43826,42.45435)
CALLE JUAN ANTONIO LLORENTE, Rincón de Soto, La Rioja, España (-1.85816,42.23313)
CALLE FRANCISCO LLORENTE, Rincón de Soto, La Rioja, España (-1.85133,42.23428)
El enfoque local se puede combinar con las distintas opciones de filtrado, con el fin de ordenar los resultados obtenidos aplicando las condiciones de filtro, en función de la distancia a un punto dado.
Filtros
En la petición autocompletar es posible filtrar de antemano los resultados de distintas maneras:
Filtrado por origen de los datos
El almacén de datos de referencia en este geocodificador permite combinar datos procedentes de distintas fuentes de datos.
Cuando se realiza una petición autocompletar, esta se dirige por defecto al conjunto de todas las direcciones 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 | calrj, mun26132 |
El siguiente ejemplo realiza una consulta autocompletar con el texto «Mayor 5» a toda la base de datos:
https://geocoder.larioja.org/v1/autocomplete?text=Mayor 5
Esta petición ofrece como resultados datos procedentes de los siguientes proveedores:
| Código | Proveedor |
|---|---|
| Comunidad Autónoma de La Rioja | calrj |
Para realizar una petición autocompletar dirigida solamente a los datos de la Comunidad Autónoma de La Rioja, debemos utilizar la siguiente sintaxis:
https://geocoder.larioja.org/v1/autocomplete?text=Mayor 5&sources=calrj
procediendo en este caso de la Comunidad Autónoma de La Rioja todos los resultados obtenidos.
Filtrado por tipo de datos
El almacenamiento de datos permite, igual que en otros métodos, diferenciar tres tipos de datos: dirección (address) ; calle (street) y lugar (venue).
Mediante el parámetro
layers
es posible 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, address, street |
El siguiente ejemplo realiza la búsqueda de calles, vías o carreteras que contengan la palabra «agreda»: https://geocoder.larioja.org/v1/autocomplete?text=agreda&layers=street
En la siguiente imagen se muestra el mapeado del fichero GeoJSON que contiene los resultados de la petición.
Filtrado por área rectangular
El método autocompletar permite condicionar los posibles resultados a aquellos que se encuentran ubicados dentro de un área geográfica rectangular. Para ello es necesario conocer de antemano las coordenadas latitud y longitud, mínimas y máximas, que definen el rectángulo (4) .
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 (1) | 42.4732824 |
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 (1) | -2.3676873 |
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 (1) | 42.4205850 |
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 (1) | -2.4811247 |
Por ejemplo, para encontrar la relación de posibles resultados de una dirección que contenga el texto «mayor 3» en el entorno de Logroño, dentro del área rectangular que muestra la imagen, definida por las coordenadas lat_min=42.4205850; lon_min=-2.4811247; lat_max=42.4732824; lon_max=-2.3676873.
La sintaxis a utilizar es:
siendo estos los resultados obtenidos:
CALLE MAYOR 3, Logroño, La Rioja, España (-2.44268,42.46834)
CALLE SANCHO EL MAYOR 3, Logroño, La Rioja, España (-2.46263,42.45783)
Como se puede comprobar en la siguiente imagen, todos los posibles resultados se encuentran comprendidos dentro del área especificada en la petición.
Filtrado por área circular
Entre las restricciones que se pueden aplicar en la búsqueda al vuelo que implementa el método autocompletar se incluye la posibilidad de restringir los resultados propuestos entre los que se encuentran dentro de un área circular determinada. En este caso es necesario definir un punto de referencia y el radio en km del círculo dentro del cual se realiza la búsqueda de soluciones.
Los parámetros a utilizar para realizar este filtrado 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 un área circular (4) | 42.46456 |
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 un área circular (4) | -2.44660 |
boundary.circle.radius
|
numérico coma flotante | no | 50 | Valor del radio (kilómetros) utilizado en la búsqueda en un área circular (4) | 10 |
Por ejemplo, para encontrar una dirección que contenga el texto "mayor 3" en un área circular de 10 km desde Logroño (La Rioja), con coordenadas de referencia (lat,lon) 42.46456,-2.44660.
La sintaxis a utilizar es:
Que arroja el siguiente resultado:
CALLLE MAYOR 3, Logroño, La Rioja, España
CALLE MAYOR 3, Alberite, La Rioja, España
CALLE MAYOR BAJA 3, Fuenmayor, La Rioja, España
CALLE MAYOR ALTA 3, Fuenmayor, La Rioja, España
CALLE SANCHO EL MAYOR 3, Logroño, La Rioja, España
La consulta cartográfica de estos puntos muestra el siguiente resultado.
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.
(6)
Se aconseja implementar en el navegador web un complemento para la visualización estructurada de ficheros
JSON.
(7)
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.
La documentación técnica de esta página web reutiliza información original de la API, disponible en el repositorio Github: https://github.com/pelias/documentation.