API do Google Elevation

Bem-vindo à documentação do desenvolvedor da Google Elevation API! A Google Elevation API fornece uma interface simples para consultas de locais na Terra e obtenção de dados de elevação. Você também pode solicitar dados de elevação com base em pontos de amostragem ao longo dos caminhos e calcular mudanças de elevação nos trajetos.

Observação: Esta API não requer uma chave da Google Maps API!

Em vez disso, os clientes da Google Maps API Premier devem assinar seus URLs usando uma nova chave criptográfica que será enviada a eles. Consulte a documentação da API Premier para obter mais informações.

O que você pode fazer com a Elevation API?

A Elevation API fornece dados para todos os locais na superfície da Terra, incluindo locais em solos oceânicos a grandes profundezas (que retornam valores negativos). Em casos como esse, para os quais o Google não possui medidas de elevação precisas para o local exato da sua solicitação, o serviço intervirá e retornará um valor aproximado usando os quatro locais mais próximos.

Com a Elevation API, você pode desenvolver aplicativos de caminhada e ciclismo, aplicativos de posicionamento para celular ou aplicativos de pesquisa de opinião de baixa resolução.

Você acessa a Elevation API por meio de uma interface HTTP. Os usuários da Google JavaScript API V3 também podem acessar essa API diretamente usando o objeto ElevationService(). Consulte Serviço de elevação para obter mais informações.

A Elevation API é um serviço novo, e gostaríamos muito de receber o seu feedback. Para isso, basta participar do grupo de discussão da Google Maps API.

Público

Este documento destina-se a desenvolvedores de sites na web e de celular que desejam usar dados de elevação de mapas fornecidos por uma das APIs do Google Maps. Ele fornece uma introdução ao uso da API e cita materiais sobre os parâmetros disponíveis.

Limites de uso

O uso da API do Google Elevation está sujeito ao limite de 2.500 solicitações por dia (os usuários Premier podem enviar até 100.000 solicitações por dia). Em cada solicitação, você pode consultar a elevação de até 512 locais, mas não pode exceder o total de 25.000 locais por dia (1.000.000 por usuários Premier). Esse limite é aplicado para impedir o uso abusivo e/ou indevido da Elevation API e pode ser alterado futuramente sem aviso prévio. Além disso, aplicamos também um limite de taxa de solicitação para evitar o uso abusivo do serviço. Se você exceder o limite de 24 horas ou fizer qualquer outro uso abusivo do serviço, a Elevation API poderá ficar temporariamente indisponível para você. Se continuar excedendo esse limite, seu acesso à Elevation API poderá ser bloqueado.

A Elevation API retorna dados para consultas de pontos individuais com o máximo de precisão possível. As consultas em lote que envolvem vários locais podem retornar dados com menos precisão, principalmente se os locais estiverem espalhados, pois pode ocorrer suavização dos dados.

Além disso, os URLs da API do Google Elevation podem ter até 2.048 caracteres, antes da codificação do URL. Como alguns URLs de serviço de elevação podem envolver muitos pontos, lembre-se desse limite ao criar seus URLs.

Observação: A Elevation API pode ser usada apenas em conjunto com a exibição de resultados em um mapa do Google; é proibido usar dados de elevação sem exibir um mapa para o qual os dados de elevação tenham sido solicitados. Para obter informações detalhadas sobre o uso permitido, consulte as Restrições de licença dos Termos de Serviço da Google Maps API.

Solicitações de elevação

A Elevation API retorna dados de elevação para locais na Terra. É possível especificar dados de locais de duas formas:

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

Ambos os métodos usam coordenadas de latitude/longitude para identificar os locais ou vértices de caminho. Este documento descreve o formato necessário para os URLs da Elevation API e os parâmetros disponíveis.

Um URL da Google Elevation API deve ter o seguinte formato:

http://maps.googleapis.com/maps/api/elevation/outputFormat?parameters

Dica: você também pode acessar a API do Google Elevation usando SSL, substituindo https por http no URL de solicitação. O HTTPS é recomendado para aplicativos que incluem dados confidenciais de usuários, como o local de um usuário, nas solicitações.

Formatos de saída

Os formatos de saída são especificados por meio do sinalizador do serviço no final do URL de solicitação. No momento, a Elevation API suporta os seguintes formatos de saída:

• /json retorna resultados em JavaScript Object Notation (JSON).
• /xml retorna resultados em XML, inseridos em um nó <ElevationResponse>.

Uso de parâmetros

As solicitações para a Elevation API usam parâmetros diferentes para solicitações de locais individuais ou de caminhos ordenados. Para locais individuais, as solicitações de elevação retornam dados sobre os locais específicos informados na solicitação; para caminhos, as solicitações de elevação são baseadas em pontos de amostragem ao longo do caminho especificado.

Como é padrão em todos os URLs, todos os parâmetros são separados usando o caractere "e" comercial (&). Veja abaixo a lista de parâmetros e seus valores possíveis.

Solicitações posicionais:

• locations (obrigatório) define os locais na Terra sobre os quais dados de elevação deverão ser retornados. Esse parâmetro usa um local individual como um par de {latitude,longitude} separado por vírgula (por exemplo, "40.714728,-73.998672") ou usa vários pares de latitude/longitude informados como uma matriz ou como uma polilinha codificada. Para obter mais informações, consulte Como especificar localizações, abaixo.

OU

Solicitações para caminhos com amostragem:

• path (obrigatório) define um caminho na Terra sobre o qual dados de elevação deverão ser retornados. Este parâmetro define um conjunto de dois ou mais pares ordenados de {latitude,longitude} que definem um caminho na superfície da Terra. Esse parâmetro deve ser usado em conjunto com o parâmetro samples descrito abaixo. Para obter mais informações, consulte Como especificar caminhos, abaixo.
• samples (obrigatório) especifica o número de pontos de amostragem ao longo do caminho para os quais dados de elevação deverão ser retornados. O parâmetro samples divide o path especificado em um conjunto ordenado de pontos equidistantes ao longo do caminho.

Parâmetros de relatório:

• sensor (obrigatório) especifica se o aplicativo que está solicitando os dados de elevação está usando um sensor para determinar a localização do usuário. Esse parâmetro é obrigatório para todas as solicitações de elevação. Para obter mais informações, consulte Como indicar o uso do sensor, abaixo.

Como especificar localizações

As solicitações posicionais são indicadas pelo uso do parâmetro locations, que determina solicitações de elevação para os locais específicos informados 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 por meio do Algoritmo de polilinha codificada: locations=enc:gfo}EtohhU

As strings de coordenadas de latitude e longitude são definidas por numerais separados por vírgula em uma string de texto. Por exemplo, "40.714728,-73.998672" é um valor válido para locations. Os valores de latitude e longitude devem 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 pode assumir qualquer valor entre -180 e 180. Se você especificar um valor de latitude ou longitude inválido, a sua solicitação será rejeitada como uma solicitação inválida.

Você pode passar quantas coordenadas múltiplas quiser dentro de uma matriz de polilinhas codificadas durante a construção de um URL válido, contanto que não ultrapasse as cotas do serviço. Observe que ao passar coordenadas múltiplas, a precisão de algum dado retornado pode ser menor do que ao solicitar dados para uma coordenada individual.

Como especificar caminhos

As solicitações para caminhos com amostragem são indicadas pelos parâmetros path e samples, que definem 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. No entanto, ao contrário das solicitações posicionais, o parâmetro path especifica um conjunto ordenado de vértices. Em vez de retornar dados de elevação apenas sobre os vértices, as solicitações de caminho são baseadas em pontos de amostragem ao longo de todo o caminho, de acordo com o número de samples especificados (inclusive as extremidades).

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

• Uma matriz de duas ou mais strings de texto de coordenada com valores separados por vírgula, sendo cada string separada por um caractere de barra vertical ("|"): path=40.714728,-73.998672|-34.397,150.644
• Um conjunto de coordenadas codificadas que usam o Algoritmo de polilinha codificada: path=enc:gfo}EtohhUxD@bAxJmGF

As strings de coordenadas de latitude e longitude são definidas por numerais separados por vírgula em uma string de texto. Por exemplo, "40.714728,-73.998672|-34.397, 150.644" é um valor válido para path. Os valores de latitude e longitude devem 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 pode assumir qualquer valor entre -180 e 180. Se você especificar um valor de latitude ou longitude inválido, a sua solicitação será rejeitada como uma solicitação inválida.

Você pode passar quantas coordenadas múltiplas quiser dentro de uma matriz de polilinhas codificadas durante a construção de um URL válido, contanto que não ultrapasse as cotas do serviço. Observe que ao passar coordenadas múltiplas, a precisão de algum dado retornado pode ser menor do que ao solicitar dados para uma coordenada individual.

Como indicar o uso do sensor

O uso da Google Elevation API exige que você indique se o seu aplicativo está usando um "sensor" (por exemplo, um localizador GPS) para determinar a localização do usuário. Isso é especialmente importante para dispositivos móveis.

Os aplicativos que determinam a localização do usuário por meio de um sensor devem passar sensor=true no URL de solicitação da Elevation API. Se o seu aplicativo não usa um sensor, passe sensor=false.

Respostas de elevação

Para cada solicitação válida, o serviço de Elevação retornará uma resposta de elevação no formato indicado no URL da solicitação. Cada resposta conterá os seguintes elementos:

• Um código de status de Elevação, que pode ser um dos seguintes valores:
  1. OK: indica que a solicitação da API foi realizada corretamente
  2. INVALID_REQUEST: indica que a solicitação da API estava incorreta
  3. OVER_QUERY_LIMIT: indica que o solicitante excedeu a cota
  4. REQUEST_DENIED: indica que a API não concluiu a solicitação, provavelmente porque o solicitante não incluiu um parâmetro sensor válido
  5. UNKNOWN_ERROR: indica um erro desconhecido

Uma matriz de results contendo os seguintes elementos:

• Um elemento location (contendo os elementos lat e lng) da posição para a qual os dados de elevação estão sendo calculados. Observe que para solicitações de caminho, o conjunto de elementos location conterá os pontos de amostragem definidos ao longo do caminho.
• Um elemento elevation indicando a elevação do local em metros.

Exemplos de elevação posicional

O exemplo abaixo solicita a elevação para Denver, Colorado (conhecida como "Mile High City"), no formato JSON:

http://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536,-104.9847034&sensor=true_or_false

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

O exemplo abaixo mostra várias respostas (para Denver, CO, e para Death Valley, CA) no formato JSON:

http://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536,-104.9847034|36.455556,-116.866667&sensor=true_or_false

{
  "status": "OK",
  "results": [ {
    "location": {
      "lat": 39.7391536,
      "lng": -104.9847034
    },
    "elevation": 1608.8402100
  }, {
    "location": {
      "lat": 36.4555560,
      "lng": -116.8666670
    },
    "elevation": -50.7890358
  } ]
}

A solicitação abaixo é idêntica à solicitação mostrada acima, a única diferença é ela indica a necessidade do formato de saída ser XML, por meio da sinalização do serviço /xml:

http://maps.googleapis.com/maps/api/elevation/xml?locations=39.7391536,-104.9847034|36.455556,-116.866667&sensor=true_or_false

<ElevationResponse>
 <status>OK</status> 
 <result> 
  <location> 
   <lat>39.7391536</lat> 
   <lng>-104.9847034</lng> 
  </location> 
  <elevation>1608.8402100</elevation> 
 </result> 
 <result> 
  <location> 
   <lat>36.4555560</lat> 
   <lng>-116.8666670</lng> 
  </location> 
  <elevation>-50.7890358</elevation> 
 </result> 
</ElevationResponse>

Exemplos de elevação de caminho

Os exemplos abaixo solicitam dados de elevação ao longo de um path de linha reta partindo de Mt. Whitney, CA, até Badwater, CA, os pontos mais alto e mais baixo nos Estados Unidos continental. Nós solicitamos dados sobre três samples, portanto, a resposta incluirá as duas extremidades e o ponto localizado na metade do caminho.

http://maps.googleapis.com/maps/api/elevation/json?path=36.578581,-118.291994|36.23998,-116.83171&samples=3&sensor=true_or_false

{
  "status": "OK",
  "results": [ {
    "location": {
      "lat": 36.5785810,
      "lng": -118.2919940
    },
    "elevation": 4411.9418945
  }, {
    "location": {
      "lat": 36.4115029,
      "lng": -117.5602608
    },
    "elevation": 1381.8616943
  }, {
    "location": {
      "lat": 36.2399800,
      "lng": -116.8317100
    },
    "elevation": -84.6169968
  } ]
}

Como criar gráficos de elevação

Os dados de elevação devem ser usados em conjunto com uma exibição dos dados em um mapa do Google. A Google Chart API (http://code.google.com/apis/chart/) é adequada para a criação de gráficos de elevação que você pode exibir juntamente com seus mapas.

O exemplo em Python abaixo calcula os dados de elevação entre Mt. Whitney e Badwater, em Death Valley, e usa esses valores para criar um gráfico de elevação:

import simplejson
import urllib

ELEVATION_BASE_URL = 'http://maps.googleapis.com/maps/api/elevation/json'
CHART_BASE_URL = 'http://chart.apis.google.com/chart'

def getChart(chartData, chartDataScaling="-500,5000", chartType="lc",chartLabel="Elevation in Meters",chartSize="500x160",chartColor="orange", **chart_args):
    chart_args.update({
      'cht': chartType,
      'chs': chartSize,
      'chl': chartLabel,
      'chco': chartColor,
      'chds': chartDataScaling,
      'chxt': 'x,y',
      'chxr': '1,-500,5000'
    })

    dataString = 't:' + ','.join(str(x) for x in chartData)
    chart_args['chd'] = dataString.strip(',')

    chartUrl = CHART_BASE_URL + '?' + urllib.urlencode(chart_args)

    print chartUrl

    def getElevation(path="36.578581,-118.291994|36.23998,-116.83171",samples="100",sensor="false", **elvtn_args):
      elvtn_args.update({
        'path': path,
        'samples': samples,
        'sensor': sensor
      })

      url = ELEVATION_BASE_URL + '?' + urllib.urlencode(elvtn_args)
      response = simplejson.load(urllib.urlopen(url))

      # Create a dictionary for each results[] object
      elevationArray = []

      for resultset in response['results']:
        elevationArray.append(resultset['elevation'])

      # Create the chart passing the array of elevation data
      getChart(chartData=elevationArray)

if __name__ == '__main__':
    # Mt. Whitney
    startStr = "36.578581,-118.291994"
    # Death Valley
    endStr = "36.23998,-116.83171"

    pathStr = startStr + "|" + endStr

    getElevation(pathStr)

As imagens abaixo mostram como essas informações podem ser exibidas em um mapa e/ou gráfico:

Faça download do código ElevationChartCreator.py em gmaps-samples.