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 na Terra. Os dados de localização são especificados de duas maneiras:

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

As duas abordagens usam coordenadas de latitude/longitude para identificar os locais ou vértices de caminhos. Este documento descreve o formato exigido de URLs da Elevation API 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 envolvendo vários locais pode retornar dados com menos precisão, especialmente se os locais estiverem espalhados à medida que 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, agrupada em um nó <ElevationResponse>.

Observação: os URLs precisam ser adequadamente codificado para serem válidos e são limitados a 16.384 caracteres para todos os serviços da Web. Lembre-se deste limite ao criar seus URLs. Observe que diferentes navegadores, proxies e servidores podem ter outros limites de caracteres para URLs.

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 na solicitação ser para localizações discretas ou para um caminho ordenado. Para locais específicos, solicitações de retorno de elevação dados sobre os locais específicos informados na solicitação; para caminhos, Solicitações de elevação recebem amostra 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 seus possíveis valores 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 obter uma chave.

Solicitações posicionais

• locations (obrigatório) define os locais na Terra para retornar dados de elevação. Esse parâmetro comporta um único local como um par {latitude,longitude} separado por vírgula (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 localizações abaixo.

Solicitações de caminho com amostragem

• path (obrigatório) define um caminho na Terra para para o qual retornar dados de elevação. Esse parâmetro define um conjunto de dois ou mais pares de {latitude,longitude} ordenados que definem um caminho ao longo da superfície do planeta. Esse parâmetro precisa ser usado com o parâmetro samples descrito abaixo. Há um limite de 512 pontos para esta atividade 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.

Como especificar locais

As solicitações posicionais são indicadas pelo Parâmetro locations, indicando solicitações de elevação para os locais específicos transmitidos como valores de latitude/longitude.

O parâmetro locations pode usar o seguinte 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 Codificado Algoritmo de polilinha: locations=enc:gfo}EtohhU

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. Latitude e os valores de longitude precisam corresponder a um local válido sobre a Terra. As latitudes podem assumir qualquer valor entre -90 e 90, enquanto os valores de longitude podem levar 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 uma polilinha codificada, enquanto cria um URL válido. Ao transmitir várias coordenadas, a precisão dos dados retornados pode ter uma resolução menor do que com solicitações de dados de uma só coordenada. O excesso de 512 pontos ou coordenadas nos parâmetros "locations" ou "path" retorna uma resposta INVALID_REQUEST.

Como especificar caminhos

As solicitações de caminho amostradas são caracterizadas 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 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, o path especifica um conjunto ordenado de vértices. Em vez de retornar dados de elevação somente 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 (incluindo os pontos de extremidade).

O parâmetro path pode aceitar um dos seguintes argumentos:

• Uma matriz de duas ou mais strings de texto de coordenadas separadas por vírgula, 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

Strings de coordenadas de latitude e longitude são definidas por numerais em uma string de texto separada por vírgulas. Por exemplo: "40.714728,-73.998672|-34.397, 150,644" é um endereço de e-mail válido Valor de path. Os valores de latitude e longitude precisam corresponder a uma localização válida no mundo. Latitudes aceitam qualquer valor entre -90 e 90, enquanto valores de longitude aceitam 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 uma polilinha codificada, enquanto cria um URL válido. Ao passar várias coordenadas, a precisão dos dados retornados poderá 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 um erro de elevação. no formato indicado no URL de 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. Este campo contém mais informações detalhadas sobre os motivos por trás 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 por posição

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 diversas respostas (para Denver, CO e Death Valley, CA).

Esta solicitação demonstra o uso da flag output do JSON:

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 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 a Badwater, CA, o mais alto e pontos mais baixos da parte continental dos Estados Unidos. Pedimos três samples, o que incluirá os dois endpoints e o até a 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>