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ê pode especificar dados de localização 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.

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 separados, já que ocorre um 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 destes valores:

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

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. Observe que 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 da 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 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 sã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 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 {latitude,longitude} separado por vírgulas (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 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 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 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 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 numerais 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 face da Terra. As latitudes podem usar qualquer valor entre -90 e 90, enquanto os valores de longitude podem usar 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.

É possível transmitir até 512 coordenadas em uma matriz ou polilinha codificada, enquanto ainda cria 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. Exceder 512 pontos ou coordenadas nos parâmetros "locations" ou "path" retorna uma resposta INVALID_REQUEST.

Especificar caminhos

As solicitações de caminho com amostragem são indicadas pelo 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 ocorre com as solicitações posicionais usando 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 caminho, com base no número de samples especificados (incluindo os endpoints).

O parâmetro path pode usar um destes argumentos:

  • Uma matriz de duas ou mais strings de texto de coordenadas separadas por vírgulas separadas usando o 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 numerais 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 face da Terra. As latitudes podem usar qualquer valor entre -90 e 90, enquanto os valores de longitude podem usar 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.

É possível transmitir até 512 coordenadas em uma matriz ou polilinha codificada, enquanto ainda cria 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. Exceder 512 pontos ou coordenadas nos parâmetros "locations" ou "path" retorna uma resposta INVALID_REQUEST.

Respostas do Elevation

  • Uma matriz de duas ou mais strings de texto de coordenadas separadas por vírgulas separadas usando o 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 numerais 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 face da Terra. As latitudes podem usar qualquer valor entre -90 e 90, enquanto os valores de longitude podem usar 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.

É possível transmitir até 512 coordenadas em uma matriz ou polilinha codificada, enquanto ainda cria 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. 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 do Elevation 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 mudanças.

ElevationStatus

Códigos de status retornados pelo serviço.

  • OK indicando que a solicitação de API foi bem-sucedida.
  • 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 um destes casos:
    • 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 indicando 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 do Elevation. 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 de resolução maiores) 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).

Essa solicitação demonstra o uso da flag output 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'

Essa solicitação demonstra o uso da flag output XML:

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 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 um path de linha reta 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.

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>