AUTOCOMPLETAR

(EN EDICIÓN)

Las aplicaciones de localización de direcciones suelen incorporar una funcionalidad de búsqueda al vuelo de direcciones, calles, topónimos y 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.

Mediante este método no es necesario lanzar una petición de geocodificicación directa especificando completamente todos los términos de la búsqueda.

El autocompletado requiere interrogar sucesivamente a la url (endpoint) de este método (/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.

En el caso de la API de geocodificación del SCN la url que responde al método autocompletar es:
https://geocoder-5-ign.larioja.org/v1/autocomplete


Ejemplo *autocompletar* (fuente: propia)


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 (1) 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 (1) -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 (1) 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 (1) 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 (1) -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 (1) 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 (1) -1.1474
focus.point.lat numérico coma flotante no ninguno Valor de la latitud utilizado en la búsqueda alrededor de un punto (1) 42.268
focus.point.lon numérico coma flotante no ninguno Valor de la longitud utilizado en la búsqueda alrededor de un punto (1) -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


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 responden bien 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 atender al 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 «madrid» genera dos peticiones síncronas: la primera con el texto «ma» y la segunda con el texto «madrid». En este caso es posible que el usuario reciba antes la respuesta a la petición «madrid» que a la petición «ma», ya que las solicitudes de autocompletar con más caracteres probablemente se resolverán más rápido, ya 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.


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-5-ign.larioja.org/v1/autocomplete?text=antoni&size=15


Respuesta 15 resultados *autocompletar* (fuente: propia)


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 (1) 42.268
focus.point.lon numérico coma flotante no ninguno Valor de la longitud utilizado en la búsqueda alrededor de un punto (1) -4.405

Por ejemplo, si se quiere centrar la petición de autocompletado del ejemplo anterior, texto=«antoni», en la ciudad de Cáceres, de coordenadas de referencia latitud,longitud: 39.4744366,-6.3719358, la sintaxis a emplear es:

https://geocoder-5-ign.larioja.org/v1/autocomplete?text=antoni&focus.point.lat=39.4744366&focus.point.lon=-6.3719358

que ofrece los siguientes 10 resultados:

Palacio Enfermería de San Antonio, CÁCERES, España
TR BARRIO SAN ANTONIO, CACERES, España
Ermita de San Antonio, CÁCERES, España
CALLE BARRIO DE SAN ANTONIO, Cáceres, España
VI BARRIO SAN ANTONIO, CACERES, España
Asociación de Vecinos Antonio Canales, CÁCERES, España
PLAZA ANTONIO CANALES, CACERES, España
Parque de Antonio Canales, CACERES, España
CALLE CATEDRATICO ANTONIO SILVA, CACERES, España
CALLE ANTONIO REYES HUERTAS, CACERES, España


Respuesta *autocompletar* Cáceres (fuente: propia)

Nota

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 Toledo de coordenadas de referencia latitud,longitud: 39.8565733,-4.0249840, la sintaxis a emplear en este caso es:

https://geocoder-5-ign.larioja.org/v1/autocomplete?text=antoni&focus.point.lat=39.8565733&focus.point.lon=-4.0249840

Arrojando los siguientes resultados:

PLAZA SAN ANTONIO, Toledo, España
CALLE ANTONIO LOPEZ, CERCA DE COBISA (LA), Toledo, España
CALLE ANTONIO SAURA, La Cruz del Portillo, Toledo, España
CALLE ANTONIO SAURA-LOS ALMENDROS, CRUZ DEL PORTILLO (LA), Toledo, España
PLAZA POETA ANTONIO MACHADO, POLIGONO SANTA MARIA DE BENQUERENCIA, Toledo, España
CALLE ANTONIO MACHADO, BARGAS, Toledo, España
CALLE SAN ANTONIO, NAMBROCA, Toledo, España
CALLE JOSE ANTONIO, LAYOS, Toledo, España


Respuesta *autocompletar* Toledo (fuente: propia)

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 un caserío de nombre «Etxegorri» con un enfoque en la población de Doneztebe/Santesteban (Navarra):

si se realiza la petición autocompletar sin especificar ningún enfoque:

https://geocoder-5-ign.larioja.org/v1/autocomplete?text=etxegorri

los resultados obtenidos por orden de preferencia son:

Etxegorri Etxea, Goizueta, Navarra, España
Etxegorri, Doneztebe/Santesteban, Navarra, España

pero sin centramos la pregunta en el entorno de la población de Doneztebe/Santesteban (Navarra) de coordenadas de referencia latitud,longitud: 43.130962,-1.6687443, el orden de las respuestas prioriza la más cercana al punto especificado:

https://geocoder-5-ign.larioja.org/v1/autocomplete?text=etxegorri&focus.point.lat=43.130962&focus.point.lon=-1.6687443

Etxegorri, Doneztebe/Santesteban, Navarra, España
Etxegorri Etxea, Goizueta, Navarra, España

Nota

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 (2)(3).

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, codificados según lista controlada Proveedores de datos cnig,calrj

El siguiente ejemplo realiza una consulta autocompletar con el texto «Mayor 5» a toda la base de datos:

https://geocoder-5-ign.larioja.org/v1/autocomplete?text=Mayor 5

Esta petición ofrece como resultados datos procedentes de los siguientes proveedores:

Código Proveedor
cnig Centro Nacional de Información Geográfica (CNIG)
dgcat Dirección General del Catastro
ieca Instituto de Estadística y Cartografía de Andalucía (IECA)
ign Instituto Geográfico Nacional (IGN)

Para realizar una petición autocompletar dirigida solamente a los datos del Instituto de Estadística y Cartografía de Andalucía (IECA), debemos utilizar la siguiente sintaxis:

https://geocoder-5-ign.larioja.org/v1/autocomplete?text=Mayor 5&sources=ieca

procediendo en este caso del IECA todos los resultados obtenidos.


Filtrado por tipo de datos


El almacenamiento de datos permite, igual que en otros métodos, diferenciar tres tipología de datos: direcciones; topónimos y puntos de interés (POIs).

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, street

Ejemplos:

Búsqueda de topónimos, puntos de interés o nombres propios de direcciones que contengan la palabra Masia: https://geocoder-5-ign.larioja.org/v1/autocomplete?text=Masia&layers=venue


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) 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 (1) -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 (1) 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 (1) -1.1474

Por ejemplo, para encontrar la relación de posibles resultados de una dirección que contenga el texto "mayor 5" en el entorno de Zaragoza, dentro del á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/autocomplete?text=mayor 5&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:

CALLE MAYOR 5, El Burgo de Ebro, Zaragoza, España
CALLE MAYOR 5, La Puebla de Alfindén, Zaragoza, España
CALLE MAYOR 5, Cuarte de Huerva, Zaragoza, España
CALLE MAYOR 5, La Muela, Zaragoza, España
CALLE MAYOR 5, NUEZ DE EBRO, Zaragoza, España
CALLE MAYORAL 5, Zaragoza, España
CALLE MAYOR (MONTAÑANA) 5, Montañana, Zaragoza, España
CALLE OSA MAYOR 5, ZARAGOZA, España
CALLE MAYOR (JUSLIBOL) 5, Juslibol, Zaragoza, España
PLAZA MAYOR (JUSLIBOL) 5, JUSLIBOL, Zaragoza, España

Como se puede comprobar en la siguiente imagen, todos los posibles resultados se encuentran comprendidos dentro del área especificada en la petición


Respuesta *autocompletar* rectángulo (fuente: propia)


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 encuentrar dentro de un área circular. 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 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 (1) 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 (1) -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 (1) 10

Por ejemplo, para encontrar una dirección que contenga el texto "mayor 5" 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/autocomplete?text=mayor 5&boundary.circle.lat=42.268&boundary.circle.lon=-4.405&boundary.circle.radius=10

Que arroja el siguiente resultado:

PLAZA MAYOR 5, Marcilla de Campos, Palencia, España
CALLE MAYOR 5, Población de Campos, Palencia, España
CALLE MAYOR 5, Boadilla del Camino, Palencia, España
PLAZA MAYOR 5, BOADILLA DEL CAMINO, Palencia, España
PLAZA MAYOR 5, VILLOVIECO, Palencia, España
PLAZA MAYOR 5, AMAYUELAS DE ARRIBA, Palencia, España
PLAZA MAYOR 5, SANTOYO, Palencia, España
TRVA MAYOR 5, BOADILLA DEL CAMINO, Palencia, España
TRAVESIA MAYOR 5, Boadilla del Camino, Palencia, España
CALLE MAYOR 5, SANTOYO, Palencia, España

La consulta cartográfica de estos puntos muestra el siguiente resultado


Respuesta *autocompletar* círculo (fuente: propia)



NOTAS:
(1) Utilizar la notación punto (.) como signo de separación decimal.
(2) En la fase de pruebas se han cargado datos de las siguientes fuentes de datos.
(3) 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 peticiones específicas mediante el parámetro sources, y evitar al mismo tiempo interferencias en los procesos de geocodificación inversa.
(4) Puede obtener las coordenadas de un rectángulo geográfico mediante la utilidad web de Klokantech.