Solicitações e respostas de elevação

Solicitações de elevação

As solicitações da API Elevation são construídas como uma string de URL. A API retorna dados de elevação para locais no planeta. 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.

Ambas as abordagens usam coordenadas de latitude/longitude para identificar os locais ou os vértices de caminho. Este documento descreve o formato obrigató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. As consultas em lote que envolvem vários locais podem retornar dados com menos precisão, especialmente se os locais estiverem espalhados, porque ocorre 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 ser um dos seguintes valores:

• json (recomendado), indica a saída em JavaScript Object Notation (JSON); ou
• xml indica a saída em XML, unida a 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 diferentes no 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 para locais específicos ou 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 são indicados abaixo.

Todas as solicitações

• key (obrigatório): a chave de API do aplicativo. Essa chave identifica o aplicativo para fins de gerenciamento de cotas. Aprenda a receber uma chave.

Solicitações posicionais

• locations (obrigatório) define localizações no planeta sobre as quais retornar dados de elevação. Esse parâmetro usa um único 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 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 no planeta para que são retornados dados de elevação. Este 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â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.

Especificar localizações

As solicitações posicionais são indicadas pelo 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 dentro de 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 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 inválida.

Você pode passar até 512 coordenadas em uma matriz ou polilinha codificada enquanto ainda constrói um URL válido. Quando várias coordenadas são passadas, a precisão dos dados retornados pode ser menor do que com solicitações de dados de uma só coordenada. Exceder 512 pontos ou coordenadas nos parâmetros "locations" ou "path" retornará uma resposta INVALID_REQUEST.

Especificar caminhos

As solicitações de caminho de amostragem são indicadas com o uso dos parâmetros path e samples, indicando 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. 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 nos vértices, as solicitações de caminho são amostradas ao longo do comprimento do caminho, com base no número de samples especificado (inclusive nos 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 ('|'): 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 dentro de 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 no planeta. 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 inválida.

Você pode passar até 512 coordenadas em uma matriz ou polilinha codificada enquanto ainda constrói um URL válido. Quando várias coordenadas são passadas, a precisão dos dados retornados pode ser menor do que com solicitações de dados de uma só coordenada. Exceder 512 pontos ou coordenadas nos parâmetros "locations" ou "path" retornará 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 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 especificado.

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 para Denver, Colorado, a "cidade de uma milha" 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 para Death Valley, CA).

Esta solicitação demonstra o uso da sinalização 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 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.

{
  "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 alto e mais baixo dos Estados Unidos continental. Solicitamos três samples, então isso incluirá os dois endpoints e o ponto da metade.

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>