Solicitações e respostas de elevação

Solicitações do Elevation

As solicitações da API Elevation são construídas como uma string de URL. A API retorna dados de elevação para locais na Terra. Você pode especificar dados de localização de duas maneiras:

• Como um conjunto de um ou mais locations.
• Como uma série de pontos conectados ao longo de um path.

Qualquer uma dessas abordagens usa coordenadas de latitude/longitude para identificar os locais ou vértices do 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 distantes, já que ocorre um ajuste 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 ser um dos seguintes valores:

• json (recomendado), indica saída em JavaScript Object Notation (JSON); ou
• xml, indica a saída em XML, envolvida em um nó <ElevationResponse>.

Observação: os URLs precisam ser codificados corretamente para serem válidos e têm um limite de 16.384 caracteres para todos os serviços da Web. Fique atento a esse limite ao criar seus URLs. Diferentes navegadores, proxies e servidores também podem ter limites de caracteres 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 com base em se a solicitação é para locais discretos ou para um caminho ordenado. Para locais discretos, 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 amostradas 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 valores possíveis estão indicados abaixo.

Todas as solicitações

• key: (obrigatório) a chave de API do seu aplicativo. Essa chave identifica o aplicativo para fins de gerenciamento de cotas. Saiba como conseguir uma chave.

Solicitações posicionais

• locations (obrigatório) define os locais na Terra sobre os quais retornar dados de elevação. Esse parâmetro usa um único local como um par {latitude,longitude} separado por vírgulas (por exemplo, "40.714728,-73.998672") ou vários pares de latitude/longitude transmitidos como uma matriz ou 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 no planeta para que são retornados dados de elevação. Esse parâmetro define um conjunto de dois ou mais pares ordenados {latitude,longitude} que definem um caminho ao longo da superfície da Terra. Ele precisa ser usado com o parâmetro 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 são retornados dados de elevação. O parâmetro samples divide o path especificado em um conjunto ordenado de pontos equidistantes ao longo do caminho.

Como 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 usando o 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 usando números em uma string de texto separada por vírgulas. Por exemplo, "40.714728,-73.998672" é um valor locations válido. Os valores de latitude e longitude precisam corresponder a um local válido na superfície da Terra. As latitudes podem ter qualquer valor entre -90 e 90, enquanto as longitudes podem ter 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 incorreta.

É possível transmitir até 512 coordenadas em uma matriz ou polilinha codificada, sem deixar de construir um URL válido. Quando várias coordenadas são passadas, a precisão dos dados retornados fica com uma resolução menor do que com solicitações de dados de uma só coordenada. Exceder 512 pontos ou coordenadas nos parâmetros "locations" ou "path" retorna uma resposta INVALID_REQUEST.

Especificar caminhos

As solicitações de caminhos amostrados são indicadas pelo uso dos 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 ocorre com as solicitações posicionais usando o parâmetro locations, o parâmetro path especifica um conjunto de valores de latitude e longitude. Diferentemente das solicitações de posição, 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 comprimento do caminho, com base no número de samples especificados (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 e pelo caractere de barra vertical ('|'): path=40.714728,-73.998672|-34.397,150.644
• Coordenadas codificadas usando o algoritmo de polilinhas codificadas: path=enc:gfo}EtohhUxD@bAxJmGF

As strings de coordenadas de latitude e longitude são definidas usando números 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 superfície da Terra. As latitudes podem ter qualquer valor entre -90 e 90, enquanto as longitudes podem ter 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 incorreta.

É possível transmitir até 512 coordenadas em uma matriz ou polilinha codificada, sem deixar de construir um URL válido. Quando várias coordenadas são passadas, a precisão dos dados retornados fica com uma resolução menor do que com solicitações de dados de uma só 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 no URL da solicitação.

Quando o código de status é diferente de OK, pode haver um campo error_message adicional no objeto de resposta de elevação. Esse campo contém informações mais detalhadas sobre os motivos do código de status fornecido.

A resposta contém uma matriz results com os seguintes elementos:

O objeto location tem os seguintes elementos:

Exemplos de elevação posicional

O exemplo a seguir solicita a elevação de Denver, Colorado, a "Mile High City", no formato JSON:

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

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

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

<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 JSON output:

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

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 conferir os exemplos de respostas JSON e XML.

{
  "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",
}

<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 altos e mais baixos dos Estados Unidos continentais. Pedimos três samples, que incluem os dois endpoints e o ponto intermediário.

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 -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'

{
  "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",
}

<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>