Solicitações de elevação
As solicitações da API Elevation são construídas como uma string de URL. Ela retorna dados de elevação para locais na Terra. Os dados de local podem ser especificados de duas maneiras:
- Como um conjunto de um ou mais
locations
. - Como uma série de pontos conectados ao longo de uma
path
.
Qualquer uma dessas abordagens usa coordenadas de latitude/longitude para identificar os locais ou vértices de caminho. Este documento descreve o formato necessário dos URLs da API Elevation e os parâmetros disponíveis.
A API Elevation retorna dados para consultas de ponto único com a maior precisão possível. Consultas em lote que envolvem vários locais podem retornar dados com menos precisão, especialmente se os locais estiverem espalhados, porque pode ocorrer alguma suavização dos dados.
Uma solicitação da API Elevation tem o seguinte formato:
https://maps.googleapis.com/maps/api/elevation/outputFormat?parameters
em que outputFormat
pode ter um destes valores:
json
(recomendado), indica a saída em JavaScript Object Notation (JSON); ouxml
, indica a saída em XML, unida em um nó<ElevationResponse>
.
Observação: os URLs precisam ser codificados corretamente para serem válidos e estão limitados a 16.384 caracteres para todos os serviços da Web. Esteja ciente desse limite ao criar seus URLs. Navegadores, proxies e servidores diferentes também podem ter limites de caracteres de URL diferentes.
O HTTPS é obrigatório para solicitações que usam uma chave de API.
Parâmetros de solicitação
As solicitações para a API Elevation usam parâmetros diferentes, dependendo se a solicitação é para locais discretos ou para um caminho ordenado. Para locais específicos, as solicitações de elevação retornam dados sobre os locais específicos transmitidos na solicitação. Para caminhos, as solicitações de elevação são baseadas em amostras ao longo do caminho especificado.
Como é padrão em todos os URLs, os parâmetros são separados usando o caractere "e" comercial (&
). Confira abaixo a lista de parâmetros e os possíveis valores.
Todas as solicitações
key
(obrigatório): chave de API do seu aplicativo. Essa chave identifica o aplicativo para fins de gerenciamento de cotas. Saiba como receber uma chave.
Solicitações posicionais
locations
(obrigatório) define locais na terra de onde os dados de elevação precisam ser retornados. Esse parâmetro usa um local como um par de {latitude,longitude} separado por vírgulas (por exemplo, "40.714728,-73.998672") ou vários pares de latitude/longitude transmitidos como uma matriz ou como uma polilinha codificada. Há um limite de 512 pontos para esse parâmetro específico. Para mais informações, consulte Como especificar locais abaixo.
Solicitações de caminho com amostragem
path
(obrigatório) define um caminho na Terra para o qual dados de elevação precisam ser retornados. Esse parâmetro define um conjunto de dois ou mais pares (latitude,longitude) ordenados que definem um caminho ao longo da superfície da Terra. Esse parâmetro precisa ser usado em conjunto com o parâmetrosamples
descrito abaixo. Há um limite de 512 pontos para esse parâmetro específico. Para mais informações, consulte Como especificar caminhos abaixo.samples
(obrigatório) especifica o número de pontos de amostra ao longo de um caminho para os quais são retornados dados de elevação. O parâmetrosamples
divide opath
especificado em um conjunto ordenado de pontos equidistantes ao longo do caminho.
Especificar locais
As solicitações posicionais são indicadas pelo uso do parâmetro locations
, que indica solicitações de elevação para os locais específicos transmitidos como valores de latitude/longitude.
O parâmetro locations
pode usar os seguintes
argumentos:
- Uma única coordenada:
locations=40.714728,-73.998672
- Uma matriz de coordenadas separadas pelo caractere de barra vertical ("
|
"):locations=40.714728,-73.998672|-34.397,150.644
- Um conjunto de coordenadas codificadas usando o algoritmo de polilinha codificada:
locations=enc:gfo}EtohhU
As strings de coordenadas de latitude e longitude são definidas por numerais em uma string de texto separada por vírgulas. Por exemplo, "40.714728,-73.998672"
é um valor de locations
válido. Os valores de latitude e longitude precisam corresponder a um local válido na face da Terra. As latitudes podem assumir qualquer valor entre -90
e 90
, enquanto os valores de longitude podem assumir qualquer valor entre -180
e 180
. Se você especificar um valor inválido de latitude ou longitude, sua solicitação será rejeitada como incorreta.
Você pode passar até 512 coordenadas em uma matriz ou polilinha codificada enquanto constrói um URL válido.
Observe que, ao passar várias coordenadas, a precisão dos dados retornados pode ter uma resolução menor do que ao solicitar dados para uma única coordenada.
Exceder 512 pontos ou coordenadas nos parâmetros "locations" ou "path" retorna uma resposta INVALID_REQUEST
.
Especificar caminhos
As solicitações de caminhos com amostragem são indicadas pelos parâmetros path
e samples
, que definem uma solicitação de dados de elevação ao longo de um caminho em intervalos especificados. Assim como acontece com as solicitações posicionais que usam o parâmetro locations
, o parâmetro path
especifica um conjunto de valores de latitude e longitude. No entanto, diferentemente das solicitações posicionais,
path
especifica um conjunto ordenado de vértices. Em vez de retornar
dados de elevação apenas nos vértices, as solicitações de caminho usam amostras ao longo do
tamanho do caminho, com base no número de samples
especificado (inclusive dos endpoints).
O parâmetro path
pode usar um dos seguintes
argumentos:
- Uma matriz de duas ou mais strings de texto de coordenadas separadas por vírgulas, separadas por um caractere de barra vertical ("
|
"):path=40.714728,-73.998672|-34.397,150.644
- Coordenadas codificadas que usam o algoritmo de polilinha codificada:
path=enc:gfo}EtohhUxD@bAxJmGF
As strings de coordenadas de latitude e longitude são definidas por numerais em uma string de texto separada por vírgulas. Por exemplo,
"40.714728,-73.998672|-34.397, 150.644" é um valor
path
válido. Os valores de latitude e longitude precisam corresponder a um local válido na face da Terra. As latitudes podem assumir qualquer valor entre -90
e 90
, enquanto os valores de longitude podem assumir qualquer valor entre -180
e 180
. Se você especificar um valor inválido de latitude ou longitude, sua solicitação será rejeitada como incorreta.
Você pode passar até 512 coordenadas em uma matriz ou polilinha codificada enquanto constrói um URL válido. Observe que, ao passar várias coordenadas, a precisão dos dados retornados pode ter uma resolução menor do que ao solicitar dados para uma única coordenada. Exceder 512 pontos ou coordenadas
nos parâmetros "locations" ou "path" retorna uma resposta INVALID_REQUEST
.
Respostas do Elevation
Para cada solicitação válida, o serviço Elevation retorna uma resposta no formato indicado no URL da solicitação.
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.
Quando o código de status for diferente de OK
, pode haver um campo error_message
extra no objeto de resposta Elevation. Esse campo contém informações mais detalhadas sobre os motivos por trás do código de status.
A resposta contém uma matriz results
com os seguintes 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. |
O objeto location
tem os seguintes 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 |
Exemplos de elevação posicional
O exemplo a seguir solicita a elevação de Denver, Colorado, a "cidade de uma milha" no 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>
O exemplo a seguir mostra várias respostas (para Denver, CO e para Vale da Morte, CA).
Esta solicitação demonstra o uso da sinalização JSON output
:
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'
Esta solicitação demonstra o uso da sinalização XML output
:
https://maps.googleapis.com/maps/api/elevation/xml?locations=39.7391536,-104.9847034|36.455556,-116.866667&key=YOUR_API_KEY
Selecione as guias abaixo para ver os exemplos de respostas JSON e XML.
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>
Os exemplos a seguir solicitam dados de elevação ao longo de uma linha reta path
do Monte Whitney, CA, até Badwater, CA, os pontos mais alto e mais baixo nos Estados Unidos continental. Pedimos três
samples
, então isso incluirá os dois endpoints e o
ponto da metade.
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>