Solicitações e respostas de elevação

Solicitações do Elevation

As solicitações da API Elevation são criadas como uma string de URL. A API retorna dados de elevação para locais na Terra. Você especifica os dados de local de uma destas duas maneiras:

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

As duas abordagens usam coordenadas de latitude/longitude para identificar os locais ou vértices de caminho. Neste documento, descrevemos 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 distantes, já que ocorre alguma suavização de 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, encapsulada 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. Considere esse limite ao criar seus URLs. Diferentes navegadores, proxies e servidores 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 são para locais específicos ou para um trajeto 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 fornecido.

Como é padrão em todos os URLs, os parâmetros são separados usando o caractere "e" comercial (&amp;). 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 seu aplicativo para fins de gerenciamento de cotas. Saiba como conseguir 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 {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 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 {latitude,longitude} ordenados que definem um caminho ao longo da superfície da Terra. Esse parâmetro 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 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 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 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 Terra. As latitudes podem assumir qualquer valor entre -90 e 90, enquanto as longitudes 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 uma solicitação inválida.

Você pode transmitir até 512 coordenadas em uma matriz ou polilinha codificada, sem deixar de criar um URL válido. Quando várias coordenadas são passadas, a precisão dos dados retornados ficam com uma resolução menor do que com solicitações de dados de uma só coordenada. Se você exceder 512 pontos ou coordenadas nos parâmetros "locations" ou "path", uma resposta INVALID_REQUEST será retornada.

Especificar caminhos

As solicitações de caminho de amostragem 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 que usam o parâmetro locations, o parâmetro path especifica um grupo 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 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 e 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 usando números em uma string de texto separada por vírgulas. 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 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 uma solicitação inválida.

Você pode transmitir até 512 coordenadas em uma matriz ou polilinha codificada, sem deixar de criar um URL válido. Quando várias coordenadas são passadas, a precisão dos dados retornados ficam com uma resolução menor do que com solicitações de dados de uma só coordenada. Se você exceder 512 pontos ou coordenadas nos parâmetros "locations" ou "path", uma resposta INVALID_REQUEST será retornada.

Respostas do Elevation

  • 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 polilinha codificada: 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 de path válido. Os valores de latitude e longitude precisam corresponder a um local válido na Terra. As latitudes podem assumir qualquer valor entre -90 e 90, enquanto as longitudes 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 uma solicitação inválida.

Você pode transmitir até 512 coordenadas em uma matriz ou polilinha codificada, sem deixar de criar um URL válido. Quando várias coordenadas são passadas, a precisão dos dados retornados ficam com uma resolução menor do que com solicitações de dados de uma só coordenada. Se você exceder 512 pontos ou coordenadas nos parâmetros "locations" ou "path", uma resposta INVALID_REQUEST será retornada.

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

Campo Obrigatório Tipo Descrição
required Array<ElevationResult> Consulte ElevationResult para mais informações.
required ElevationStatus Consulte ElevationStatus para mais informações.
opcional string

Quando o serviço retorna um código de status diferente de OK, pode haver um campo error_message adicional no objeto de resposta. Esse campo contém informações mais detalhadas sobre os motivos do código de status fornecido. Esse campo nem sempre é retornado, e o conteúdo dele está sujeito a alterações.

ElevationStatus

Códigos de status retornados pelo serviço.

  • OK: indicando que a solicitação de API funcionou.
  • DATA_NOT_AVAILABLE indicando que não há dados disponíveis para os locais de entrada.
  • INVALID_REQUEST: indicando que a solicitação de API é inválida.
  • OVER_DAILY_LIMIT indicando qualquer uma das seguintes opções:
    • A chave de API está ausente ou é inválida.
    • O faturamento não foi ativado na sua conta.
    • Um limite de uso definido pelo próprio usuário foi excedido.
    • A forma de pagamento fornecida não é mais válida (por exemplo, o cartão de crédito expirou).
  • OVER_QUERY_LIMIT: indicando que o solicitante excedeu a cota.
  • REQUEST_DENIED: indica que a API não concluiu a solicitação.
  • UNKNOWN_ERROR: indicando um erro desconhecido.

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:

ElevationResult

Campo Obrigatório Tipo Descrição
required número

A elevação do local em metros.
required LatLngLiteral

Um elemento de local da posição para que os dados de elevação são calculados. Para solicitações de caminho, o conjunto de elementos de local contém os pontos de amostra ao longo do caminho.

Consulte LatLngLiteral para mais informações.

opcional número

O valor que indica a distância máxima entre os pontos de dados entre os quais a elevação foi interpolada, em metros. Essa propriedade não vai estar presente se a resolução for desconhecida. Os dados de elevação ficam mais imprecisos (valores maiores de resolução) quando vários pontos são transmitidos. Para saber o valor de elevação mais preciso para um ponto, é necessário fazer a consulta separadamente.

LatLngLiteral

Um objeto que descreve um local específico com latitude e longitude em graus decimais.

Campo Obrigatório Tipo Descrição
required número

Latitude em graus decimais
required número

Longitude em graus decimais

Exemplos de elevação posicional

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

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 Death Valley, CA).

Esta solicitação demonstra o uso da flag 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 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 as respostas de exemplo em 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 dos Estados Unidos continentais. Pedimos três samples, que incluem 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>