Solicitudes de elevación y respuestas

Solicitudes de Elevation

Las solicitudes a la API de Elevation se construyen como una cadena de URL. La API muestra datos de elevación para ubicaciones en la superficie de la tierra. Puedes especificar los datos de ubicación de una de estas dos maneras:

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

Cualquiera de estos enfoques usan coordenadas de latitud/longitud para identificar las ubicaciones o los vértices del trayecto. En este documento, se describe el formato obligatorio para las URLs de la API de Elevation y los parámetros disponibles.

La API de Elevation muestra datos para consultas individuales con la mayor precisión posible. Las consultas en lote que incluyan múltiples ubicaciones pueden devolver datos menos precisos, especialmente si las ubicaciones están distanciadas entre sí, ya que puede ocurrir cierta unificación de los datos.

Una solicitud a la API de Elevation tiene el siguiente formato:

https://maps.googleapis.com/maps/api/elevation/outputFormat?parameters

donde outputFormat puede ser cualquiera de los siguientes valores:

• json (recomendado), indica el resultado en notación de objetos de JavaScript (JSON); o
• xml, indica el formato de salida en XML, agrupado en un nodo <ElevationResponse>.

Nota: Las URLs deben estar codificadas correctamente para ser válidas y tienen una limitación de 16,384 caracteres para todos los servicios web. Ten en cuenta este límite cuando crees tus URLs. Ten en cuenta que los diferentes navegadores, proxies y servidores también pueden tener diferentes límites de caracteres de URL.

Se requiere HTTPS para las solicitudes que usan una clave de API.

parámetros de solicitud

Las solicitudes a la API de Elevation utilizan diferentes parámetros en función de si la solicitud es para ubicaciones discontinuas o para un trayecto ordenado. Para las ubicaciones discontinuas, las solicitudes de elevación devuelven datos sobre las ubicaciones específicas que se pasaron en la solicitud; para trayectos, las solicitudes de elevación se muestrean a lo largo del trayecto especificado.

Como es norma en todas las URLs, los parámetros se separan con el signo et (&). A continuación, se proporciona una lista de los parámetros y sus posibles valores.

Todas las solicitudes

• key: (obligatorio) Es la clave de API de tu aplicación. Esta clave identifica tu aplicación a los fines de la administración de la cuota. Obtén más información para obtener una clave.

Solicitudes de posición

• locations (obligatorio) define las ubicaciones de la Tierra a partir de las cuales se muestran los datos de elevación. Este parámetro toma una ubicación individual como un par de {latitude,longitude} separado por comas (p.ej., "40.714728,-73.998672") o varios pares de latitud/longitud pasados como una matriz o una polilínea codificada. Hay un límite de 512 puntos para este parámetro específico. Para obtener más información, consulta Especificación de ubicaciones a continuación.

Solicitudes de ruta de acceso de muestra

• path (obligatorio) define una ruta en la Tierra para la cual se deben mostrar datos de elevación. Este parámetro define un conjunto de dos o más pares de coordenadas (latitud y longitud) ordenados que definen una ruta a lo largo de la superficie de la Tierra. Este parámetro se debe usar junto con el parámetro samples que se describe a continuación. Hay un límite de 512 puntos para este parámetro específico. Para obtener más información, consulta Especificación de trayectos a continuación.
• samples (obligatorio) especifica la cantidad de puntos de muestra a lo largo de una ruta para la que se muestran datos de elevación. El parámetro samples divide el objeto path determinado en un conjunto ordenado de puntos equidistantes a lo largo de la ruta.

Especificación de ubicaciones

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

El parámetro locations puede tomar los siguientes argumentos:

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

Las cadenas de coordenadas de latitud y longitud se definen con numerales 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 superficie 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 especificas un valor de latitud o longitud no válido, se rechazará tu solicitud por ser incorrecta.

Puedes pasar hasta 512 coordenadas dentro de un array o un polilínea codificado y, al mismo tiempo, crear una URL válida. Ten en cuenta que, cuando se pasan varias coordenadas, la precisión de los datos resultantes puede ser inferior que cuando se solicitan datos para una única coordenada. Si superas los 512 puntos o coordenadas en los parámetros "locations" o "path", se muestra una respuesta INVALID_REQUEST.

Especificación de rutas

Las solicitudes de trayectos muestreados se indican mediante el uso de los parámetros path y samples, que indican una solicitud de datos de elevación a lo largo de un trayecto en intervalos especificados. Al igual que con las solicitudes posicionales que usan 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, la path especifica un conjunto ordenado de vértices. En lugar de mostrar los 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 samples especificada (incluidos los extremos).

El parámetro path puede tener uno de los siguientes argumentos:

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

Las cadenas de coordenadas de latitud y longitud se definen con numerales 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 sobre la superficie 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 especificas un valor de latitud o longitud no válido, se rechazará tu solicitud por ser incorrecta.

Puedes pasar hasta 512 coordenadas dentro de un array o un polilínea codificado y, al mismo tiempo, crear una URL válida. Ten en cuenta que, cuando se pasan varias coordenadas, la precisión de los datos resultantes puede ser inferior que cuando se solicitan datos para una única coordenada. Si superas los 512 puntos o coordenadas en los parámetros "locations" o "path", se muestra una respuesta INVALID_REQUEST.

Respuestas de Elevation

Para cada solicitud válida, el servicio Elevation mostrará una respuesta de Elevation en el formato indicado en la URL de la solicitud.

ElevationResponse

Field	Required	Type	Description
results	required	Array<ElevationResult>	See ElevationResult for more information.
status	required	ElevationStatus	See ElevationStatus for more information.
error_message	optional	string	When the service returns a status code other than OK, there may be an additional error_message field within the response object. This field contains more detailed information about thereasons behind the given status code. This field is not always returned, and its content is subject to change.

ElevationStatus

Status codes returned by service.

• OK indicating the API request was successful.
• DATA_NOT_AVAILABLE indicating that there's no available data for the input locations.
• INVALID_REQUEST indicating the API request was malformed.
• OVER_DAILY_LIMIT indicating any of the following:
  • The API key is missing or invalid.
  • Billing has not been enabled on your account.
  • A self-imposed usage cap has been exceeded.
  • The provided method of payment is no longer valid (for example, a credit card has expired).
• OVER_QUERY_LIMIT indicating the requestor has exceeded quota.
• REQUEST_DENIED indicating the API did not complete the request.
• UNKNOWN_ERROR indicating an unknown error.

Cuando el código de estado no es OK, es posible que haya un campo error_message adicional dentro del objeto de respuesta de Elevation. Este campo contiene información más detallada sobre los motivos del código de estado determinado.

Nota: No se garantiza que este campo aparezca siempre, y su contenido está sujeto a modificaciones.

La respuesta contiene un array results con los siguientes elementos:

ElevationResult

Field	Required	Type	Description
elevation	required	number	The elevation of the location in meters.
location	required	LatLngLiteral	A location element of the position for which elevation data is being computed. Note that for path requests, the set of location elements will contain the sampled points along the path. See LatLngLiteral for more information.
resolution	optional	number	The value indicating the maximum distance between data points from which the elevation was interpolated, in meters. This property will be missing if the resolution is not known. Note that elevation data becomes more coarse (larger resolution values) when multiple points are passed. To obtain the most accurate elevation value for a point, it should be queried independently.

El objeto location tiene los siguientes elementos:

LatLngLiteral

An object describing a specific location with Latitude and Longitude in decimal degrees.

Field	Required	Type	Description
lat	required	number	Latitude in decimal degrees
lng	required	number	Longitude in decimal degrees

Ejemplos de elevación posicional

En el siguiente ejemplo, se solicita la elevación de Denver, Colorado, la "ciudad de un kilómetro de altura", en formato JSON:

URL

https://maps.googleapis.com/maps/api/elevation/json
  ?locations=39.7391536%2C-104.9847034
  &key=YOUR_API_KEY

cURL

curl -L -X GET 'https://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536%2C-104.9847034&key=YOUR_API_KEY'

JSON

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

XML

<ElevationResponse>
 <status>OK</status>
 <result>
  <location>
   <lat>39.7391536</lat>
   <lng>-104.9847034</lng>
  </location>
  <elevation>1608.6379395</elevation>
  <resolution>4.7719760</resolution>
 </result>
</ElevationResponse>

En el siguiente ejemplo, se muestran varias respuestas (para Denver, Colorado, y para Death Valley, California).

En esta solicitud, se muestra el uso de la marca output de JSON:

URL

https://maps.googleapis.com/maps/api/elevation/json
  ?locations=39.7391536%2C-104.9847034%7C36.455556%2C-116.866667
  &key=YOUR_API_KEY

cURL

curl -L -X GET 'https://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536%2C-104.9847034%7C36.455556%2C-116.866667&key=YOUR_API_KEY'

En esta solicitud, se muestra el uso de la marca output de XML:

https://maps.googleapis.com/maps/api/elevation/xml?locations=39.7391536,-104.9847034|36.455556,-116.866667&key=YOUR_API_KEY

Selecciona las pestañas que se indican a continuación para ver las respuestas JSON y XML de muestra.

JSON

{
  "results":
    [
      {
        "elevation": 1608.637939453125,
        "location": { "lat": 39.7391536, "lng": -104.9847034 },
        "resolution": 4.771975994110107,
      },
      {
        "elevation": -52.79492568969727,
        "location": { "lat": 36.455556, "lng": -116.866667 },
        "resolution": 19.08790397644043,
      },
    ],
  "status": "OK",
}

XML

<ElevationResponse>
 <status>OK</status>
 <result>
  <location>
   <lat>39.7391536</lat>
   <lng>-104.9847034</lng>
  </location>
  <elevation>1608.6379395</elevation>
  <resolution>4.7719760</resolution>
 </result>
 <result>
  <location>
   <lat>36.4555560</lat>
   <lng>-116.8666670</lng>
  </location>
  <elevation>-52.7949257</elevation>
  <resolution>19.0879040</resolution>
 </result>
</ElevationResponse>

En los siguientes ejemplos, se solicitan datos de elevación en una línea recta path desde Mt. Whitney, California, hasta Badwater, California, los puntos más alto y más bajo del territorio continental de los Estados Unidos. Solicitamos tres samples, de modo que se incluirán los dos extremos y el punto intermedio.

URL

https://maps.googleapis.com/maps/api/elevation/json
  ?path=36.578581%2C-118.291994%7C36.23998%2C-116.83171
  &samples=3
  &key=YOUR_API_KEY

cURL

curl -L -X GET 'https://maps.googleapis.com/maps/api/elevation/json?path=36.578581%2C-118.291994%7C36.23998%2C-116.83171&samples=3&key=YOUR_API_KEY'

JSON

{
  "results":
    [
      {
        "elevation": 4411.94189453125,
        "location": { "lat": 36.578581, "lng": -118.291994 },
        "resolution": 19.08790397644043,
      },
      {
        "elevation": 1372.8359375,
        "location": { "lat": 36.41150289067028, "lng": -117.5602607523847 },
        "resolution": 9.543951988220215,
      },
      {
        "elevation": -84.51690673828125,
        "location": { "lat": 36.23998, "lng": -116.83171 },
        "resolution": 9.543951988220215,
      },
    ],
  "status": "OK",
}

XML

<ElevationResponse>
 <status>OK</status>
 <result>
  <location>
   <lat>36.5785810</lat>
   <lng>-118.2919940</lng>
  </location>
  <elevation>4411.9418945</elevation>
  <resolution>19.0879040</resolution>
 </result>
 <result>
  <location>
   <lat>36.4115029</lat>
   <lng>-117.5602608</lng>
  </location>
  <elevation>1372.8359375</elevation>
  <resolution>9.5439520</resolution>
 </result>
 <result>
  <location>
   <lat>36.2399800</lat>
   <lng>-116.8317100</lng>
  </location>
  <elevation>-84.5169067</elevation>
  <resolution>9.5439520</resolution>
 </result>
</ElevationResponse>