La API de Elevación proporciona una interfaz simple cuya función es consultar una ubicación para obtener sus datos de elevación.
Entendemos por elevación de una ubicación geográfica, a la altura por encima o por debajo de un punto de referencia fijo, el cual es el nivel del mar. Este término se usa principalmente cuando se hace referencia a puntos en la superficie de la Tierra y se diferencia de la altitud porque esta se utiliza para puntos que están en la atmosfera terrestre.
Esta API es una buena herramienta para desarrollar aplicaciones de senderismo y ciclismo, aplicaciones de posicionamiento o aplicaciones topográficas de baja resolución, ya que permite solicitar datos de elevación durante una ruta para calcular los cambios de elevación.
Los datos de elevación están disponibles para cualquier ubicación en la superficie de la Tierra, además de ubicaciones de profundidad dentro del océano. En los casos en los que Google no posee las medidas de elevación exactas en la ubicación solicitada, la API interpola y devuelve un valor promedio usando las cuatro ubicaciones más cercanas. Los valores de elevación se expresan en relación con el nivel medio del mar (LMSL).
Se accede a la API de Elevation a través de interfaz HTTP, a través de URL, usando coordenadas (altitud/longitud) para identificar las ubicaciones de la ruta solicitada. Esta solicitud ya debe incluir la API key. Aquí un ejemplo de como se debe ver el URL:
https://maps.googleapis.com/maps/api/elevation/json?locations=19.4286157%2C-99.2067666
&key=YOUR_API_KEY
En la página de la documentacion de esta API está el código ejemplo para varios lenguajes de programación
Para probar este URL, ingréselo en su navegador web. La respuesta va a incluir la elevación en ese punto, en metros, junto con el valor de resolución (la distancia máxima entre los puntos de datos a partir de los cuales se interpoló la elevación, también en metros).
Se deben especificar los datos de localización de dos formas: un set de una o más localizaciones o bien, una serie de puntos conectados a lo largo de una ruta. Cualquiera de los dos utiliza coordenadas de latitud y longitud para identificar un lugar, una línea o un perímetro.
Cuando se hace una solicitud de un solo punto, el resultado contiene la exactitud más alta posible; cuando la solicitud es de múltiples locaciones, los resultados podrían tener menos exactitud, especialmente si estas están muy separadas unas de otras.
La URL para la solicitud tiene esta forma
https://maps.googleapis.com/maps/api/elevation/outputFormat?parameters
Donde outputFormat puede ser alguno de estos dos valores:
- json (recomendado) el cual hace referencia al JavaScritp Object Notation, o bien,
- xml, que indica una salida en este formato dentro de un nodo de <ElevationResponse>.
Parámetros
Los parámetros se emplean en función de si la solicitud es para ubicaciones puntuales donde devuelve datos específicos para las mismas, o cuando es para una ruta, donde las solicitudes están “muestreadas” a lo largo de esa línea.
Los parámetros se separan con el carácter ampersand (&) como es estándar en las URL.
Aquí la lista de los diferentes parámetros y sus posibles valores:
Para todas las solicitudes:
- Key – (indispensable) es la API key de tu aplicativo, esta llave identifica tu aplicación para temas de costos.
Ubicaciones:
- Ubicaciones (locations), es indispensable y define el punto(s) en la Tierra de donde regresara la información de elevación. Puede ser la coordenada de un solo punto, separado por coma (latitud, longitud), o múltiples coordenadas expresadas como una matriz o una polilínea codificada.
Muestreo a lo largo de una ruta:
- Ruta (path), define la ruta en la superficie terrestre de la cual se quiere conocer las diferentes elevaciones. Este parámetro define un set de dos o más coordenadas y debe ser utilizado en conjunto con la cantidad de muestras a lo largo de la ruta.
- Muestreo (samples), específica la cantidad de puntos muestra a lo largo de la ruta que se está solicitando. Este parámetro divide la ruta solicitada en puntos equidistantes a lo largo de la misma.
Especificando ubicaciones:
Las solicitudes de posición se indican mediante el uso del parámetro de ubicación, que indica la elevación para coordenadas específicas
Este parámetro de ubicación puede tomar alguno de las siguientes formas:
- Una sola coordenada: locations=19.4286157,-99.2067666
- Una matriz de coordenadas separadas por el carácter de barra vertical, “|” (pipe character): locations=40.714728,-73.998672|-34.397,150.644
- Un set de coordenadas codificadas utilizando el Algoritmo de Codificación de Polilíneas: locations=enc:gfo}EtohhU
Las coordenadas deben estar definidas empleando las comas para separar los números dentro de la URL, debe ser un valor de ubicación válido en la faz de la tierra. Las latitudes pueden tomar cualquier valor entre -90 y 90, mientras que los valores de longitud pueden tomar cualquier valor entre -180 y 180. Si introduce un valor de latitud o longitud no válido, su solicitud será marcada como incorrecta.
Es posible solicitar hasta 512 coordenadas dentro de una matriz o polilínea codificada; si supera esta cantidad, la solicitud devuelve la respuesta INVALID_REQUEST. Cómo lo dijimos anteriormente, en una matriz de coordenadas la precisión de los datos devueltos puede ser de menor resolución que cuando se solicitan datos para una sola coordenada.
Definiendo rutas:
A diferencia de una solicitud posicional, cuando se define una ruta (path) se hace mediante un conjunto ordenado de vértices. En lugar de devolver datos de elevación solo en los vértices, las solicitudes de ruta se muestrean a lo largo de la ruta, según la cantidad de muestras especificadas (incluidos los puntos finales).
El parámetro de ruta (path) puede construirse con cualquiera de estas opciones:
- Una matriz de dos o más coordenadas separadas con el caracter pipe, path=40.714728,-73.998672|-34.397,150.644
- Un set de coordenadas codificadas utilizando el Algoritmo de Codificación de Polilíneas: path=enc:gfo}EtohhUxD@bAxJmGF
Como hemos podido leer, esta API es una excelente opción para saber la ruta que ha seguido un transporte sin recurrir a otras APIs como Route Traveled. También es utilizada como parte de los parámetros para crear algoritmos que infieren el consumo de gasolina en el rastreo de activos o de calorías, como sería una aplicación de ejercicio.
El costo de la API Elevation, es de 5 USD por cada 1000 consultas, esto significa .005 centavos de dólar por cada llamada, como todas las APIs también tiene descuentos escalonados dependiendo del consumo mensual.
Bibliografía
https://developers.google.com/maps/documentation/elevation/start
https://developers.google.com/maps/documentation/elevation/usage-and-billing