API Géocodificación

Introducción

Open Street es un servicio de optimización de itinerarios que permite calcular un itinerario en el orden ideal para disminuir la distancia recorrida.

Nuestra aplicación web en línea utiliza las API Open Street, especialmente aquellas que permiten la geocodificación, es decir, la transformación entre una dirección postal y una coordenada de latitud, longitud.

Ejecutar una geocodifcación con la API

Protocolo utilizado

Esta API utiliza el método GET implementado en el protocolo HTTP 1.1. Podemos utilizarlo desde un navegador web estándar o cualquier otra biblioteca para descargar datos desde un servidor web. Esta API de geocodificación es susceptible de recibir caracteres especiales o acentuados, que deben ser codificados apropiadamente en secuencias, comenzando con un porcentaje (%). Los espacios deben ser reemplazados por más (+). Los navegadores recientes codifican automáticamente las direcciones URL, pero no siempre las bibliotecas HTTP.

Todas nuestras API son compatibles con la compresión gzip, por lo que es muy recomendable para activar esta característica en su cliente HTTP. Para verificar que la compresión está activa, el encabezado de la solicitud del cliente debe incluir Accept-Encoding: «gzip, deflate» y el encabezado de la respuesta del servidor debe incluir Content-Encoding: «gzip». Esto reduce casi un 50% del tiempo de descarga de datos.

El tiempo de respuesta de esta API es inferior a 500 ms. Gracias a nuestra memoria interna, las respuestas puede ser más rápidas si la información ya ha sido solicitada con anterioridad, del orden de unos pocos milisegundos.

Datos de entrada

Para funcionar, esta API requiere datos proporcionados como parámetros de URL. En la siguiente tabla, los asteriscos * indican los parámetros que se requieren para ejecutar un cálculo.

Parámetro	Valor	Explicación
address*	1 Rue de la Paix, Paris, France	Dirección postal lo más preciso posible, y donde los campos esten separados por comas o puntos y comas. Esta debe ser codificada como una URL.
key*	caracteres	Clave de autenticación de cada usuario.

El URL que interroga la API de geocodificación debe ser codificada correctamente, es decir que todos los caracteres especiales y acentuados son transformados por secuencias que comienzan con el signo de porcentaje (%). Los espacios deben ser transformados en un signo más (+).

Los navegadores modernos codifican automáticamente las direcciones introducidas en la barra de URL, pero este no es siempre el caso de las bibliotecas HTTP como Curl.

Un ejemplo concreto

Tomemos el ejemplo de la policia de Bourg-en-Bresse la cual tendrá la siguiente dirección « Policia de l’Ain, Bourg-en-Bresse, France ».

A continuación una muestra de la solicitud formulada por la API de geocodificación. Recuerde que se requiere una clave de autenticación valida.

Uso de datos de geocodificación

Datos de salida

El formato de datos de salida es un objeto JSON que puede ser descargado y procesado por una aplicación, o visualizado con un navegador. La compresión relacionada al protocolo HTTP es gestionado por el cliente HTTP de forma transparente para el desarrollador.

El documento obtenido es compatible con la API de geocodificación de Google, todo esto omitiendo los detalles innecesarios. Si ya ha desarrollado una aplicación que utiliza esta API, usted ya conoce el funcionamiento. Utilizamos diferentes bases de datos para este servicio, por lo que los resultados pueden variar de los de Google.

A continuación una tabla de los parámetros de salida.

Parámetros	Explicación
formatted_address	Dirección corregida tal y como fue asimilada por la API.
lat	Latitud del punto solicitado.
lng	Longitud del punto solicitado.
status	Código de estatus

La estructura del documento no fue representado en este documento, pero el objeto json contiene igualmente las cadenas siguientes : geometry, location.

Recomendaciones de uso

Cuando utilice este objeto JSON, debe recuperar los valores a traves de su cadena asociada, y no por su posición en el documento o su numero de línea. De hecho, otros datos pueden ser insertados en el futuro y esta es la única manera de respetar la compatibilidad. Es posible deshabilitar la tabla de objeto JSON de su lenguaje de programación con una biblioteca especializada, con tal de mantener las cadenas y valores. Para obtener más información sobre JSON, visite la pagina json.org que proporciona una lista de las bibliotecas de decodificación en diferentes lenguajes de programación.

Puede utilizar esta API en conjunto con nuestra API de optimización de rutas. En este caso, es recomendable comenzar tan pronto como sea posible la geocodificación, y no esperar hasta que el usuario inicie un cálculo de optimización. De esta forma, se mejorará la fluidez de su aplicación.

Si usted sabe de antemano la lista de direcciones que usted solicitara, le aconsejamos que inicie todas sus solicitudes de geocodificación una primera vez con un guión de su creación. De esta forma, todas las aplicaciones futuras se beneficiarán de nuestra memoria integrada, y serán mucho más rápidas.

A diferencia de nuestra API de optimización, nuestras rutinas de geocodificación no son particularmente más eficaces que las que están disponibles gratuitamente en internet. Así que, si sus necesidades de geocodificación son particularmente importantes, le recomendamos que se basan principalmente en Google API de codificación geográfica o un servicio equivalente, y utilizar nuestra API para codificar geográficamente solo en caso de fallo.

Los códigos de error

El código de estatus debe ser «OK». Para cualquier otro valor de retorno, la petición de geocodificación habrá fallado. La siguiente tabla describe la significación de los diferentes códigos que puede encontrar utilizando nuestra API.

Codigo	Explicación
SYNTAX_ERROR	La petición esta incompleta o contiene un error.
LIMIT_REACHED	Usted ha agotado sus cuotas de uso. Saber más.
WRONG_KEY	Su clave de autenticación es falsa. Contáctenos.
ADDRESS_IS_INCONSISTENT	La dirección demandada es una cadena de carácteres demasiado cortan o demasiado larga.
REQUEST_DENIED	Imposible de responder a esta petición.

Desarrollos futuros

• Otros parámetros facultativos podrían ser desarrollados para afinar el cálculo.
• El método GET del protocolo HTTP limita el tamaño de las solicitudes de 8 Ko.