API Rutas

Introducción

Nuestra aplicación web utiliza la API de Open Street, incluyendo aquella que muestra en un mapa el camino de un itinerario por la ruta entre los dos puntos (o más). En este artículo se describe el funcionamiento de esta API para su propio uso.

Los puntos rojos estan unidos por las rutas azules

Los puntos rojos estan unidos por las rutas azules

En la imagen anterior podemos constatar los puntos rojos y las etapas en azul. Una etapa, un punto de partida y una destinación. Para trazar una etapa, utilizamos una polilínea, es decir, una línea discontinua que consiste en una sucesión de coordenadas GPS.

Consultar una ruta 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 optimización no es susceptible de recibir caracteres especiales o acentuados, pero las direcciones URL deben ser codificadas correctamente. 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 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 la cabecera de la respuesta del servidor debe incluir Content-Encoding: “gzip”. Esto permite reduce casi un 50% del tiempo de descarga de datos. La compresión es particularmente eficaz con esta API, por lo que es importante activarla.

El tiempo de respuesta de esta API es inferior a 100ms, que las peticiones se hayan solicitado o no préviamente.

Datos de entrada

Para funcionar, este API requiere datos que son 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ámetros Valor Explicación
origin* 48.856614,2.352221 Coordenada del punto de partida. Los números deben contener un máximo de 10 décimales.
destination* 45.764043,4.835659 Coordenada del punto de llegada. Los números deben contener un máximo de 10 décimales.
mode* driving ou walking Médio de transporte coche (conduciendo) o a pie (caminando).
key* chaine-de-caracteres Clave de autenticación de cada usuario.

Un ejemplo concreto

Tomemos el ejemplo de un itinerario entre Paris y Lyon (Francia).

quí una muestra de la solicitud formulada por la API de polílineas. Tome en cuenta que una clave de autenticación valida es requerida.

Uso de datos

Datos de salida

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

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

Parámetro Explicación
polyline Canal de carácteres que contienen la ruta geógrafica.
total_distance Distancia en m.
total_time Tiempo en segundos.
status Código de estatus.

La estructura del objeto JSON es muy simple. El valor detrás del canal “polilínea” puede alcanzar varias decenas de kilobytes. Es por eso que insistimos en gran medida sobre la necesidad de activar por parte del cliente la compresión gzip.

Este es un método para codificar una lista de coordenadas geográficas que describen una trayectoria. Ha sido definido por Google y está confirmado por varios proyectos de mapeo. Este es un método eficaz para “comprimir” una larga lista de coordenadas a una cadena de carácteres más cortos.

El bloque anterior es el resultado producido por nuestra API. Para facilitar la lectura, la polilínea se ha bloqueado y por lo tanto no es válida.

Recomendaciones de uso

Cuando se utlice el objeto JSON, debe recuperar los valores a traves de su canal asociado, 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. Para obtener más información sobre JSON, visite el sitio 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 recorridos o nuestra API de geocodificación.

No hay una memoria enlazada a esta API, por lo tanto no hay esperanza de ganancia mediante la repetición de un cálculo varias veces.

Para una perfecta superposición de la polilínea con su mapa de fondo, se recomienda el uso de un mapa de soluciones proveniente del proyecto OpenStreetMap. Podemos aconsejarle al respecto necesario.

Los códigos de error

El código de estado estándar debe ser “OK”. Para cualquier otro valor de retorno, la solicitud habrá fracasado. La siguiente tabla describe el significado de los diferentes códigos que pueden presentarse al utilizar nuestra API.

Codigo Explicación
SYNTAX_ERROR La solicitud esta incompleta o contiene un error.
LIMIT_REACHED Usted ha agotado sus cuotas de uso. Saber mas.
WRONG_KEY Su clave de autenticación es falsa. Contáctenos.
REQUEST_DENIED Imposible responder a esta solicitud.

Ejemplo de utilización

Usted lo ha entendido, una polilínea es una cadena que una vez interpretada correctamente por una aplicación cartografica, se muestra como una trayectoria en un mapa. Se puede convertir en una lista de coordenadas de latitud, longitud a través de una función de decodificación apropiado. Se pueden encontrar en el Internet.

En la decodificación, se debe tener mucho cuidado con la precisión decimal utilizada anteriormente cuando se codifica. Las polilíneas API de Google codifican con una precisión de 5 decimales, mientras que nuestros polilíneas API tiene una precisión de 6 decimales.

Muchas bibliotecas cartográficas son compatibles con este formato, especialmente OpenLayers, Leaflet, Google Maps y Bing Maps.

Una página de demostración de la trayectoria de polilíneas con Leaflet.encoded está disponible aquí. A continuación una lista de los proyectos relacionados con este tema.