Solicitudes de Elevation
Las solicitudes a la API de Elevation se construyen como una cadena de URL. La API devuelve datos de elevación para ubicaciones de la Tierra. Especifica los datos de ubicación de 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 usa coordenadas de latitud y longitud para identificar la ubicaciones o vértices de ruta de acceso. Este documento describe el formato requerido las URLs de la API de Elevation y los parámetros disponibles.
La API de Elevation muestra datos para consultas de un solo punto con la mayor exactitud posible. Consultas por lotes que involucran varias ubicaciones puede devolver datos con menos exactitud, especialmente si las ubicaciones están dispersas a medida que se suavizan los datos.
Una solicitud a la API de Elevation toma la siguiente forma:
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 objeto de JavaScript (JSON) oxml
, indica el formato de salida en XML, unido a una<ElevationResponse>
nodo.
Nota: Las URLs deben tener la codificación adecuada y tienen un límite de 16,384 caracteres para todos los servicios web. Ten en cuenta este límite cuando construyas tus direcciones URL. Ten en cuenta que los diferentes navegadores los proxies y los servidores también pueden tener distintos límites de caracteres para las URL.
Se requiere HTTPS para las solicitudes que usan una clave de API.
parámetros de solicitud
Las solicitudes a la API de Elevation usan parámetros diferentes en función de si la solicitud es para ubicaciones discretas o para una ruta de acceso ordenada. Para ubicaciones discretas, solicitudes de devolución de elevación datos sobre las ubicaciones específicas que se pasaron en la solicitud de rutas, En cambio, las solicitudes de elevación se muestrean a lo largo de la ruta determinada.
Como es norma en todas las URLs, los parámetros están separados
con el carácter et (&
). La lista de parámetros
y sus posibles valores
se indican a continuación.
Todas las solicitudes
key
: (obligatorio) de la aplicación Clave de API. 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 posicionales
locations
(obligatorio) define las ubicaciones en la de la Tierra desde la cual obtener los datos de elevación. Este parámetro toma un valor una sola ubicación como un par de {latitude,latitude} separado por comas (p.ej., "40.714728,-73.998672") o varios pares de latitud y longitud o 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 Cómo especificar ubicaciones a continuación.
Solicitudes de rutas de muestra
path
(obligatorio) define una ruta en la Tierra para para obtener datos de elevación. Este parámetro define un conjunto de dos o pares de {latitude,length} más ordenados que definen una ruta a lo largo de la superficie de la Tierra. Este parámetro se debe usar junto consamples
según se describe a continuación. Existe un límite de 512 puntos para esta actividad. parámetro específico. Para obtener más información, consulta Cómo especificar rutas a continuación.samples
(obligatorio) especifica la cantidad de muestras. puntos a lo largo de una ruta para la que se devolverán datos de elevación. El El parámetrosamples
divide elpath
especificado en un conjunto ordenado de puntos equidistantes a lo largo de la ruta.
Cómo especificar ubicaciones
Las solicitudes posicionales se indican mediante el uso de la
Parámetro locations
, que indica solicitudes de elevación
para las ubicaciones específicas que se pasaron como
valores de latitud y longitud.
El parámetro locations
puede tener lo siguiente
argumentos:
- Una sola coordenada:
locations=40.714728,-73.998672
- Un array de coordenadas separadas con la barra vertical (“
|
”) carácter:locations=40.714728,-73.998672|-34.397,150.644
- Un conjunto de coordenadas codificadas que usan el
Codificado
Algoritmo de polilínea:
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 de locations
válido. Latitud y
los valores de longitud deben corresponder a una ubicación válida
sobre la faz de la Tierra. Las latitudes pueden tener cualquier valor entre
-90
y 90
, mientras que los valores de longitud pueden
cualquier valor entre -180
y 180
. Si especificas
un valor de latitud o longitud no válido, se rechazará tu solicitud
como una mala solicitud.
Puedes pasar hasta 512 coordenadas en una matriz o codificado
polilínea, al mismo tiempo que se crea una URL válida.
Ten en cuenta que, cuando se pasan coordenadas múltiples, la precisión de los datos devueltos
puede ser de menor resolución que cuando se solicitan datos para una sola coordenada.
Superar los 512 puntos o coordenadas en las "ubicaciones" o "path" parámetro muestra un
INVALID_REQUEST
respuesta.
Cómo especificar rutas de acceso
Las solicitudes de ruta de muestra se indican mediante el uso de path
.
y los parámetros samples
, que indican una solicitud de datos de elevación
a lo largo de una ruta en intervalos específicos. Al igual que con las solicitudes posicionales que usan
parámetro locations
, el parámetro path
especifica
un conjunto de valores de latitud y longitud. Sin embargo, a diferencia de lo que ocurre con una solicitud posicional,
path
especifica un conjunto ordenado de vértices. En lugar de regresar
datos de elevación solo en los vértices, se muestrean solicitudes de rutas a lo largo del
de la ruta, según la cantidad de samples
especificado (incluidos los extremos).
El parámetro path
puede tomar cualquiera de las siguientes opciones
argumentos:
- Array de dos o más cadenas de texto de coordenadas separadas por comas
separadas con la barra vertical (“
|
”) carácter:path=40.714728,-73.998672|-34.397,150.644
- Coordenadas codificadas con el
Codificado
Algoritmo de polilínea:
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 válido
Valor path
. Los valores de latitud y longitud deben corresponder
a una ubicación válida sobre la superficie de la Tierra. Las latitudes pueden tener cualquier valor entre
-90
y 90
, mientras que los valores de longitud pueden
cualquier valor entre -180
y 180
. Si especificas
un valor de latitud o longitud no válido, se rechazará tu solicitud
como una mala solicitud.
Puedes pasar hasta 512 coordenadas en una matriz o codificado
polilínea, al mismo tiempo que se crea una URL válida. Ten en cuenta que cuando pasas varios
coordenadas, la precisión de los datos devueltos puede ser de menor resolución que
cuando solicitas datos para una sola coordenada. Superar los 512 puntos o coordenadas
en la carpeta "locations" o "path" parámetros muestra una respuesta INVALID_REQUEST
.
Respuestas de Elevation
Para cada solicitud válida, el servicio Elevation devolverá una respuesta en el formato indicado en la URL de la solicitud.
ElevationResponse
Field | Required | Type | Description |
---|---|---|---|
| required | Array<ElevationResult> | See ElevationResult for more information. |
| required | ElevationStatus | See ElevationStatus for more information. |
| optional | string |
When the service returns a status code other than |
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 es distinto de OK
, puede haber una indicación
Campo error_message
en el objeto de respuesta de Elevation. Este campo contiene más
información detallada sobre los motivos del código de estado proporcionado.
La respuesta contiene un array results
con los siguientes elementos:
ElevationResult
Field | Required | Type | Description |
---|---|---|---|
| required | number | The elevation of the location in meters. |
| 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. |
| 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 |
---|---|---|---|
| required | number | Latitude in decimal degrees |
| required | number | Longitude in decimal degrees |
Ejemplos de elevación posicional
En el siguiente ejemplo, se solicita la elevación para Denver, Colorado, la “Mile High City” 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>
El siguiente ejemplo muestra respuestas múltiples (para Denver, CO y para Muerte Valley, California).
En esta solicitud, se muestra el uso de la marca output
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 aparecen 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, CA hasta Badwater, CA, el aeropuerto más alto y
los puntos más bajos del territorio continental de los Estados Unidos. Pedimos tres
samples
, por lo que incluirá 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>