Elevation API

La API de elevación proporciona una interfaz simple para consultar ubicaciones en la tierra para obtener datos de elevación. Además, puede solicitar datos de elevación de muestra a lo largo de las rutas, lo que le permite calcular los cambios de altura a lo largo de las rutas. Con la API de elevación, puede desarrollar aplicaciones de senderismo y ciclismo, aplicaciones de posicionamiento o aplicaciones topográficas de baja resolución.

Los datos de elevación están disponibles para todas las ubicaciones en la superficie de la tierra, incluidas las ubicaciones de profundidad en el fondo del océano (que devuelven valores negativos). En aquellos casos en los que Google no posee medidas de elevación exactas en la ubicación precisa que solicita, el servicio interpola y devuelve un valor promedio utilizando las cuatro ubicaciones más cercanas. Los valores de elevación se expresan en relación con el nivel medio del mar local (LMSL).

Puede acceder a la API de elevación a través de una interfaz HTTP. Los usuarios de la API de JavaScript de Maps también pueden acceder a esta API directamente utilizando el objeto ElevationService(). (Consulte Elevation Service para obtener más información).

Antes de que empieces

Este documento está destinado a desarrolladores de sitios web y dispositivos móviles que deseen utilizar datos de elevación en mapas proporcionados por una de las API de Google Maps Platform. Proporciona una introducción al uso de la API y material de referencia sobre los parámetros disponibles.

Antes de comenzar a desarrollar con la API de elevación, revise los requisitos de autenticación (necesita una clave de API) y el uso de la API y la información de facturación (debe habilitar la facturación en su proyecto).

Solicitudes de elevación

Las solicitudes de la API de elevación se construyen como una cadena de URL. La API devuelve datos de elevación para ubicaciones en la tierra. Los datos de ubicación se especifican de una de estas dos formas:

• Como un conjunto de uno o más locations.
• Como una serie de puntos conectados a lo largo de a path.

Cualquiera de estos enfoques utiliza coordenadas de latitud / longitud para identificar las ubicaciones o los vértices de la ruta. Este documento describe el formato requerido de las URL de la API de elevación y los parámetros disponibles.

La API de elevación devuelve datos para consultas de un solo punto con la mayor precisión posible. Las consultas por lotes que involucran múltiples ubicaciones pueden devolver datos con menos precisión, especialmente si las ubicaciones están separadas, ya que se produce un suavizado de datos.

Una solicitud de API de elevación tiene la siguiente forma:

donde outputFormat puede ser cualquiera de los siguientes valores:

• json(recomendado), indica la salida en notación de objetos JavaScript (JSON); o
• xml, indica salida en XML, envuelto dentro de un nodo <ElevationResponse>.

Solicitar parámetros

Las solicitudes a la API de elevación utilizan diferentes parámetros en función de si la solicitud es para ubicaciones discretas o para una ruta ordenada. Para ubicaciones discretas, las solicitudes de datos de retorno de elevación sobre las ubicaciones específicas pasadas en la solicitud; en el caso de las rutas, las solicitudes de elevación se muestrean a lo largo de la ruta dada.

Como es estándar en todas las URL, los parámetros se separan mediante el carácter comercial ( &). La lista de parámetros y sus posibles valores se indican a continuación.

Todas las solicitudes

• key- ( obligatorio ) La clave API de su aplicación. Esta clave identifica su aplicación a los efectos de la gestión de cuotas. Aprenda a obtener una llave .

Solicitudes posicionales

• locations (obligatorio) define la (s) ubicación (es) en la tierra desde la cual devolver los datos de elevación. Este parámetro toma una sola ubicación como un par {latitud, longitud} separados por comas (por ejemplo, "40.714728, -73.998672") o varios pares de latitud / longitud pasados ​​como una matriz o como una polilínea codificada. Para obtener más información, consulte Especificación de ubicaciones a continuación.

Solicitudes de ruta de muestra

• path(obligatorio) define una ruta en la tierra para la cual devolver datos de elevación. Este parámetro define un conjunto de dos o más pares {latitud, longitud} ordenados que definen un camino a lo largo de la superficie de la tierra. Este parámetro debe utilizarse junto con el parámetro samples que se describe a continuación. Para obtener más información, consulte Especificación de rutas a continuación.
• samples (obligatorio) especifica el número de puntos de muestra a lo largo de una ruta para los que devolver datos de elevación. El parámetro samples divide el path dado  en un conjunto ordenado de puntos equidistantes a lo largo de la ruta.

Especificar ubicaciones

Las solicitudes de posición se indican mediante el uso del parámetro locations, que indica las solicitudes de elevación para las ubicaciones específicas pasadas como valores de latitud/longitud.

El parámetro locations puede tener los siguientes argumentos:

• Una sola coordenada: locations=40.714728,-73.998672
• Una matriz de coordenadas separadas mediante el carácter de barra vertical (' |'):locations=40.714728,-73.998672|-34.397,150.644
• Un conjunto de coordenadas codificadas mediante el algoritmo de polilínea codificada :locations=enc:gfo}EtohhU

Las cadenas de coordenadas de latitud y longitud se definen utilizando números dentro de una cadena de texto separada por comas. Por ejemplo, "40.714728, -73.998672" es un valor locations válido. Los valores de latitud y longitud deben corresponder a una ubicación válida en la faz de la tierra. Las latitudes pueden tomar cualquier valor entre -90y, 90mientras que los valores de longitud pueden tomar cualquier valor entre -180y 180. Si especifica un valor de latitud o longitud no válido, su solicitud será rechazada como una solicitud incorrecta.

Puede pasar cualquier número de coordenadas múltiples dentro de una matriz o polilínea codificada, mientras sigue construyendo una URL válida. Tenga en cuenta que al pasar varias coordenadas, la precisión de los datos devueltos puede ser de menor resolución que cuando se solicitan datos para una sola coordenada.

Especificando rutas

Las solicitudes de ruta muestreadas se indican mediante el uso de los parámetros path y samples, lo que indica una solicitud de datos de elevación a lo largo de una ruta a intervalos específicos. Al igual que con las solicitudes posicionales que utilizan el parámetro locations, el parámetro path especifica un conjunto de valores de latitud y longitud. Sin embargo, a diferencia de una solicitud posicional, path  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 el número de samples especificados (incluidos los extremos).

El parámetro path puede tomar cualquiera de los siguientes argumentos:

• Una matriz de dos o más cadenas de texto de coordenadas separadas por comas separadas mediante el carácter de barra vertical (' |'):path=40.714728,-73.998672|-34.397,150.644
• Coordenadas codificadas mediante el algoritmo de polilínea codificada :path=enc:gfo}EtohhUxD@bAxJmGF

Las cadenas de coordenadas de latitud y longitud se definen utilizando números dentro de una cadena de texto separada por comas. Por ejemplo, "40.714728, -73.998672 | -34.397, 150.644" es un valor path válido . Los valores de latitud y longitud deben corresponder a una ubicación válida en la faz de la tierra. Las latitudes pueden tomar cualquier valor entre -90y, 90mientras que los valores de longitud pueden tomar cualquier valor entre -180y 180. Si especifica un valor de latitud o longitud no válido, su solicitud será rechazada como una solicitud incorrecta.

Puede pasar cualquier número de coordenadas múltiples dentro de una matriz o polilínea codificada, mientras sigue construyendo una URL válida. Tenga en cuenta que al pasar varias coordenadas, la precisión de los datos devueltos puede ser de menor resolución que cuando se solicitan datos para una sola coordenada.

Respuestas de elevación

Para cada solicitud válida, el servicio de Elevación devolverá una respuesta de Elevación en el formato indicado en la URL de la solicitud. Cada respuesta contendrá los siguientes elementos:

Un código status de elevación , que puede ser uno de los siguientes:

• OK indicando que la solicitud de API fue exitosa.
• INVALID_REQUEST lo que indica que la solicitud de la API tenía un formato incorrecto.
• OVER_DAILY_LIMIT indicando cualquiera de los siguientes:
  • Falta la clave API o no es válida.
  • No se ha habilitado la facturación en su cuenta.
  • Se superó un límite de uso autoimpuesto.
  • El método de pago proporcionado ya no es válido (por ejemplo, una tarjeta de crédito ha caducado).

  Consulte las preguntas frecuentes de Maps para saber cómo solucionar este problema.

• OVER_QUERY_LIMIT indicando que el solicitante ha excedido la cuota.
• REQUEST_DENIED indicando que la API no completó la solicitud.
• UNKNOWN_ERROR indicando un error desconocido.

Cuando el código de estado es distinto de OK, puede haber un campo error_message adicional dentro del objeto de respuesta Elevación. Este campo contiene información más detallada sobre las razones detrás del código de estado dado.

Una matriz que resultscontiene los siguientes elementos:

• Un locationelemento (que contiene lat y lngelementos) de la posición para la que se calculan los datos de elevación. Tenga en cuenta que para las solicitudes de ruta, el conjunto de locationelementos contendrá los puntos muestreados a lo largo de la ruta.
• Un elevationelemento que indica la elevación de la ubicación en metros.
• Un resolutionvalor, que indica la distancia máxima entre los puntos de datos desde lo
• s que se interpola la elevación, en metros. Esta propiedad faltará si no se conoce la resolución. Tenga en cuenta que los datos de elevación se vuelven más gruesos ( resolutionvalores más grandes ) cuando se pasan varios puntos. Para obtener el valor de elevación más preciso para un punto, debe consultarse de forma independiente.

Ejemplos de elevación posicional

El siguiente ejemplo solicita la elevación de Denver, Colorado, la "Ciudad de una milla de altura" en formato JSON:

{
   "results" : [
      {
         "elevation" : 1608.637939453125,
         "location" : {
            "lat" : 39.73915360,
            "lng" : -104.98470340
         },
         "resolution" : 4.771975994110107
      }
   ],
   "status" : "OK"
}

El siguiente ejemplo muestra varias respuestas (para Denver, CO y para Death Valley, CA).

Esta solicitud demuestra el uso de la bandera output JSON:

Esta solicitud demuestra el uso de la bandera output XML :

Los siguientes ejemplos solicitan datos de elevación a lo largo de un path de línea recta desde el Monte Whitney, CA a Badwater, CA, los puntos más altos y más bajos en los Estados Unidos continentales. Pedimos tres samples, por lo que incluirán los dos puntos finales y el punto medio.

{
   "results" : [
      {
         "elevation" : 4411.941894531250,
         "location" : {
            "lat" : 36.5785810,
            "lng" : -118.2919940
         },
         "resolution" : 19.08790397644043
      },
      {
         "elevation" : 1381.861694335938,
         "location" : {
            "lat" : 36.41150289067028,
            "lng" : -117.5602607523847
         },
         "resolution" : 19.08790397644043
      },
      {
         "elevation" : -84.61699676513672,
         "location" : {
            "lat" : 36.239980,
            "lng" : -116.831710
         },
         "resolution" : 19.08790397644043
      }
   ],
   "status" : "OK"
}

Crear gráficos de elevación

Los datos de elevación deben usarse junto con una visualización de datos en un mapa de Google. La API de gráficos ( https://code.google.com/apis/chart/) es adecuada para crear gráficos de elevación que puede mostrar junto con sus mapas.

El siguiente ejemplo de Python calcula los datos de elevación entre el Monte Whitney y Badwater, Death Valley y usa esos valores para crear un gráfico de elevación:

import simplejson
import urllib

ELEVATION_BASE_URL = 'https://maps.googleapis.com/maps/api/elevation/json'
CHART_BASE_URL = 'https://chart.apis.google.com/chart'

def getChart(chartData, chartDataScaling="-500,5000", chartType="lc",chartLabel="Elevation in Meters",chartSize="500x160",chartColor="orange", **chart_args):
    chart_args.update({
      'cht': chartType,
      'chs': chartSize,
      'chl': chartLabel,
      'chco': chartColor,
      'chds': chartDataScaling,
      'chxt': 'x,y',
      'chxr': '1,-500,5000'
    })

    dataString = 't:' + ','.join(str(x) for x in chartData)
    chart_args['chd'] = dataString.strip(',')

    chartUrl = CHART_BASE_URL + '?' + urllib.urlencode(chart_args)

    print chartUrl

    def getElevation(path="36.578581,-118.291994|36.23998,-116.83171",samples="100", **elvtn_args):
      elvtn_args.update({
        'path': path,
        'samples': samples
      })

      url = ELEVATION_BASE_URL + '?' + urllib.urlencode(elvtn_args)
      response = simplejson.load(urllib.urlopen(url))

      # Create a dictionary for each results[] object
      elevationArray = []

      for resultset in response['results']:
        elevationArray.append(resultset['elevation'])

      # Create the chart passing the array of elevation data
      getChart(chartData=elevationArray)

if __name__ == '__main__':
    # Mt. Whitney
    startStr = "36.578581,-118.291994"
    # Death Valley
    endStr = "36.23998,-116.83171"

    pathStr = startStr + "|" + endStr

    getElevation(pathStr)

Las siguientes imágenes muestran cómo se puede mostrar esta información en un mapa y/o gráfico:

Descargue el código ElevationChartCreator.py de js-v2-samples.

El parámetro sensor

La API de Google Maps anteriormente requería que incluyera el parámetro sensor para indicar si su aplicación usaba un sensor para determinar la ubicación del usuario. Este parámetro ya no es necesario.