Esta página foi traduzida pela API Cloud Translation.

Solicitações e respostas de elevação

Solicitações de Elevation

As solicitações da Elevation API são construídas como uma string de URL. Ela retorna dados de elevação para locais no planeta. É possível especificar 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 uma dessas abordagens usa coordenadas de latitude/longitude para identificar os locais ou vértices de caminho. Neste documento, descrevemos o formato necessário dos URLs da API Elevation e os parâmetros disponíveis.

A API Elevation retorna dados para consultas de pontos únicos com a maior precisão possível. As consultas em lote envolvendo vários locais podem retornar dados com menos precisão, especialmente se os locais estiverem espalhados, já que ocorre uma 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) ou
xml, indica a saída em XML, encapsuladas em um nó <ElevationResponse>.

Observação: os URLs precisam ser codificados corretamente 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. 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 para solicitações de locais específicos ou de caminhos ordenados. 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 têm amostras 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 os possíveis valores são descritos abaixo.

Todos os pedidos

key (obrigatório): a 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 os locais na terra dos quais retornar dados de elevação. Esse parâmetro usa um único local como um par de {latitude,longitude} separado por vírgula (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 ver mais informações, consulte Como especificar locais abaixo.

Solicitações de caminho com amostragem

path (obrigatório) define um caminho na Terra sobre o qual dados de elevação deverão ser retornados. Esse parâmetro define um conjunto de dois ou mais pares ordenados de {latitude,longitude} que definem um caminho ao longo da superfície da Terra. Use esse parâmetro com o samples 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 dados de elevação serão retornados. O parâmetro samples divide o path fornecido em um conjunto ordenado de pontos equidistantes ao longo do caminho.

Especificar locais

As solicitações posicionais são indicadas com o uso do parâmetro locations, que determina 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 que usam o algoritmo de polilinha codificada: locations=enc:gfo}EtohhU

As strings de coordenadas de latitude e longitude são definidas por numerais separados por vírgulas em uma string de texto. Por exemplo, "40.714728,-73.998672" é um valor locations válido. Os valores de latitude e longitude precisam corresponder a um local válido no mundo. 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 de latitude ou longitude inválido, sua solicitação será rejeitada como inválida.

Você pode passar até 512 coordenadas dentro de uma matriz ou polilinha codificada e, ao mesmo tempo, construir um URL válido. Ao passar várias coordenadas, a precisão dos dados retornados pode ter uma resolução menor do que com a solicitação de 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 indicam 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, 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 são amostradas ao longo do tamanho do caminho, com base no número de samples especificados (incluindo os 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 pelo caractere de barra vertical ("|"): path=40.714728,-73.998672|-34.397,150.644
Coordenadas codificadas usando o algoritmo de polilinha codificada: path=enc:gfo}EtohhUxD@bAxJmGF

As strings de coordenadas de latitude e longitude são definidas por numerais separados por vírgulas em uma string de texto. Por exemplo, "40.714728,-73.998672|-34.397, 150.644" é um valor de 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 de latitude ou longitude inválido, sua solicitação será rejeitada como inválida.

Você pode passar até 512 coordenadas dentro de uma matriz ou polilinha codificada e, ao mesmo tempo, construir um URL válido. Ao passar várias coordenadas, a precisão de qualquer dado retornado 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 de elevação no formato indicado pelo URL da solicitação.

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.

Quando o código de status é diferente de OK, pode haver um campo error_message extra no objeto de resposta de elevação. Esse campo contém informações mais 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
`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.

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
`lat`	required	number	Latitude in decimal degrees
`lng`	required	number	Longitude in decimal degrees

Exemplos de elevação posicional

O exemplo a seguir solicita a elevação de Denver, Colorado, conhecida como "Mile High City", 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 Vale da Morte, CA).

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, até Badwater, CA, nos pontos mais alto e mais baixo dos Estados Unidos continental. Solicitamos três samples, então isso vai incluir os dois endpoints e o ponto intermediário.

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>

Solicitações e respostas de elevação

Solicitações de Elevation

Parâmetros de solicitação

Todos os pedidos

Solicitações posicionais

Solicitações de caminho com amostragem

Especificar locais

Especificar caminhos

Respostas do Elevation

ElevationResponse

`results`

`status`

`error_message`

ElevationStatus

ElevationResult

`elevation`

`location`

`resolution`

LatLngLiteral

`lat`

`lng`

Exemplos de elevação posicional

URL

cURL

JSON

XML

URL

cURL

JSON

XML

URL

cURL

JSON

XML