Solicitações de Elevation
As solicitações da Elevation API são construídas como uma string de URL. A API retorna dados de elevação para locais na Terra. Você especifica os dados de local de duas maneiras:
- Como um conjunto de um ou mais
locations
. - Como uma série de pontos conectados ao longo de uma
path
.
Qualquer um desses métodos usa coordenadas de latitude/longitude para identificar locais ou vértices de caminho. Este documento descreve o formato exigido de URLs da API Elevation e os parâmetros disponíveis.
A Elevation API retorna dados para consultas de ponto único com a maior precisão possível. Consultas em lote envolvendo vários locais pode retornar dados com menos precisão, especialmente se os locais estiverem espalhados à medida que ocorre alguma suavização dos dados.
Uma solicitação da Elevation API tem o seguinte formato:
https://maps.googleapis.com/maps/api/elevation/outputFormat?parameters
em que outputFormat
pode ser um dos seguintes valores:
json
(recomendado), indica a saída em JavaScript Object Notation (JSON) ouxml
, indica a saída em XML, encapsulada em uma Nó<ElevationResponse>
.
Observação: os URLs precisam ser adequadamente codificado para serem válidos e são limitados a 16.384 caracteres para todos os serviços da Web. Esteja ciente desse limite ao criar seus URLs. Observe que diferentes navegadores, proxies e servidores também podem ter diferentes limites de caracteres de URL.
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 de a solicitação ser para locais específicos caminho ordenado. Para locais específicos, solicitações de retorno de elevação dados sobre os locais específicos informados na solicitação; para caminhos, Solicitações de elevação recebem amostra ao longo do caminho especificado.
Como é padrão em todos os URLs, os parâmetros são separados
usando o caractere E comercial (&
). A lista de parâmetros
e seus possíveis valores estão indicados abaixo.
Todas as solicitações
key
(obrigatório): o domínio Chave de API. Essa chave identifica o aplicativo para fins de gerenciamento de cotas. Saiba como receber uma chave.
Solicitações posicionais
locations
(obrigatório) define os locais na Terra da qual dados de elevação deverão ser retornados. Esse parâmetro recebe uma único local como um par {latitude,longitude} separado por vírgula (por exemplo, "40.714728,-73.998672") ou vários pares de latitude/longitude passado como uma matriz ou como uma polilinha codificada. Há um limite de 512 pontos para este parâmetro específico. Para mais informações, consulte Especificar localizações abaixo.
Solicitações de caminho com amostragem
path
(obrigatório) define um caminho na Terra para para o qual retornar dados de elevação. Esse parâmetro define um conjunto de duas ou mais pares ordenados de {latitude,longitude} que definem um caminho na superfície do planeta. Esse parâmetro precisa ser usado comsamples
. descrito abaixo. Há um limite de 512 pontos para esta atividade parâmetro específico. Para mais informações, consulte Como especificar caminhos abaixo.samples
(obrigatório) especifica o número de amostras pontos ao longo de um caminho para os quais dados de elevação deverão ser retornados. A O parâmetrosamples
divide opath
fornecido em um conjunto ordenado de pontos equidistantes ao longo do caminho.
Especificar locais
As solicitações posicionais são indicadas pelo
Parâmetro locations
, indicando solicitações de elevação
para os locais específicos transmitidos como
valores de latitude/longitude.
O parâmetro locations
pode usar o seguinte
argumentos:
- Uma única coordenada:
locations=40.714728,-73.998672
- Uma matriz de coordenadas separadas por uma barra vertical ("
|
") caractere:locations=40.714728,-73.998672|-34.397,150.644
- Um conjunto de coordenadas codificadas que usam o
Codificado
Algoritmo de polilinha:
locations=enc:gfo}EtohhU
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. Latitude e
os valores de longitude precisam corresponder a um local válido
sobre a Terra. As latitudes podem assumir qualquer valor entre
-90
e 90
, enquanto os valores de longitude podem levar
qualquer valor entre -180
e 180
. Se você especificar
um valor de latitude ou longitude inválido, sua solicitação será rejeitada
como uma solicitação inválida.
Você pode passar até 512 coordenadas dentro de uma matriz ou codificadas
polilinha enquanto ainda cria um URL válido.
Ao passar várias coordenadas, a precisão dos dados retornados
podem ter uma resolução menor do que ao solicitar dados para uma única coordenada.
Excedendo 512 pontos ou coordenadas em "locais" ou "path" de parâmetros retorna um
INVALID_REQUEST
.
Especificar caminhos
As solicitações de caminho de amostra são indicadas por path
.
e samples
, indicando uma solicitação de dados de elevação.
ao longo de um caminho em intervalos especificados. Assim como nas solicitações posicionais que usam o
parâmetro locations
, o parâmetro path
especifica
um conjunto de valores de latitude e longitude. No entanto, ao contrário das solicitações posicionais,
o path
especifica um conjunto ordenado de vértices. Em vez de retornar
dados de elevação apenas sobre os vértices, as solicitações de caminho são coletadas com amostragem ao longo do
tamanho do caminho, com base no número de samples
especificado (incluindo os endpoints).
O parâmetro path
pode usar uma das seguintes opções:
argumentos:
- Uma matriz de duas ou mais strings de texto de coordenadas separadas por vírgula
separados usando a barra vertical ("
|
") caractere:path=40.714728,-73.998672|-34.397,150.644
- Coordenadas codificadas que usam o
Codificado
Algoritmo de polilinha:
path=enc:gfo}EtohhUxD@bAxJmGF
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 endereço de e-mail válido
path
. Os valores de latitude e longitude devem corresponder
em um local válido na face da Terra. As latitudes podem assumir qualquer valor entre
-90
e 90
, enquanto os valores de longitude podem levar
qualquer valor entre -180
e 180
. Se você especificar
um valor de latitude ou longitude inválido, sua solicitação será rejeitada
como uma solicitação inválida.
Você pode passar até 512 coordenadas dentro de uma matriz ou codificadas
polilinha enquanto ainda cria um URL válido. Ao passar várias
coordenadas, a precisão dos dados retornados poderá ter uma resolução menor do que
ao solicitar dados para uma única coordenada. Exceder 512 pontos ou coordenadas
em "locations" ou "path" retorna uma resposta INVALID_REQUEST
.
Respostas do Elevation
Para cada solicitação válida, o serviço Elevation retorna um erro de elevação. no formato indicado no URL de 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 é diferente de OK
, pode haver um
error_message
no objeto de resposta de elevação. Este campo contém mais
informações detalhadas sobre os motivos por trás do código de status fornecido.
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 para 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, Califórnia).
Esta solicitação demonstra o uso da flag output
do 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'
Esta solicitação demonstra o uso da flag 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 a Badwater, CA, o mais alto e
pontos mais baixos da parte continental dos Estados Unidos. Pedimos três
samples
, o que incluirá os dois endpoints e o
até a 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>