Pronto!

Para começar a desenvolver, acesse nossa documentação do desenvolvedor.

Ativar a Google Maps JavaScript API

Para começar, orientaremos você pelo Console do Desenvolvedor do Google para realizar algumas atividades:

  1. Criar ou selecionar um projeto
  2. Ativar a Google Maps JavaScript API e serviços relacionados
  3. Criar chaves apropriadas
Continuar

Serviço Elevation

Visão geral

O serviço Elevation fornece dados de elevação para todas as localizações na superfície do planeta, incluindo localizações profundas no fundo do oceano (que retornam valores negativos). Quando o Google não tem medidas exatas de elevação do local preciso solicitado, o serviço faz uma interpolação e retorna um valor médio usando as quatro localizações mais próximas.

O objeto ElevationService oferece uma interface simples para consultar dados de elevação em localizações no planeta. Além disso, você pode solicitar amostragens de dados de elevação ao longo de caminhos, o que permite calcular mudanças de elevação equidistantes ao longo das rotas. O objeto ElevationService se comunica com o serviço Elevation da Google Maps API, que recebe solicitações de elevação e retorna dados de elevação.

O serviço Elevation permite desenvolver aplicativos para trilha e ciclismo, aplicativos de posicionamento móvel ou aplicativos de levantamento topográfico de baixa resolução.

Primeiros passos

Antes de usar o serviço Elevation da Google Maps JavaScript API, verifique se a Google Maps Elevation API está ativa no Google API Console, no mesmo projeto que você criou para a Google Maps JavaScript API.

Para ver a lista de APIs ativadas:

  1. Acesse o Google API Console.
  2. Clique no botão Select a project, selecione o mesmo projeto que você criou para a Google Maps JavaScript API e clique em Open.
  3. Na lista de APIs do Painel, procure a Google Maps Elevation API.
  4. Se achar a API na lista, está tudo pronto. Se não, ative-a:
    1. Na parte superior da tela, selecione ENABLE API para exibir a guia Library. É possível também selecionar Library no menu à esquerda.
    2. Procure a Google Maps Elevation API e, em seguida, selecione-a na lista de resultados.
    3. Selecione ENABLE. Depois do fim do processo, Google Maps Elevation API aparece na lista de APIs no Painel.

Políticas e limites de uso

Cotas

Os limites de uso a seguir são aplicados ao serviço Elevation:

Uso do serviço Elevation no Plano padrão

  • 2.500 solicitações gratuitas por dia, calculadas pela soma das consultas do cliente e do servidor; ativar cobrança para ter acesso a maiores cotas diárias, com custo de US$ 0,50 para 1.000 solicitações adicionais, até 100.000 solicitações por dia.
  • 512 locais por solicitação.
  • 50 solicitações por segundo, calculadas pela soma das consultas do cliente e do servidor.

Uso do serviço Elevation no Plano premium

  • Cota diária compartilhada gratuita de 100.000 solicitações a cada 24 horas. Solicitações adicionais mediante compra anual de crédito das Maps APIs.
  • 512 locais por solicitação.
  • Ilimitada solicitações do cliente por segundo por projeto. Observe que a API do servidor tem limite de 50 solicitações por segundo.

Limite de taxa aplicado por sessão de usuário, independentemente de quantos usuários compartilham o projeto.

O limite de taxa por sessão impede o uso de serviços do lado do cliente para fazer solicitações em lote. Em vez disso, para calcular elevações para localizações estáticas e conhecidas, use o Google Maps Elevation API Web Service.

Políticas

O uso do serviço Elevation deve estar de acordo com as políticas descritas para a Google Maps Elevation API.

Solicitações de Elevation

O acesso ao serviço Elevation é assíncrono, pois a Google Maps API precisa chamar um servidor externo. Por isso, passe um método de retorno de chamada a ser executado na conclusão da solicitação. Esse método de retorno de chamada processa os resultados. Note que o serviço Elevation retorna um código de status (ElevationStatus) e uma matriz de objetos ElevationResult separados.

O ElevationService processa dois tipos de solicitação:

  • Solicitações de localizações separadas e discretas usando o método getElevationForLocations(), que recebe uma lista de uma ou mais localizações usando um objeto LocationElevationRequest.
  • Solicitações de elevação para uma série de pontos conectados ao longo de um caminho usando o método getElevationAlongPath(), que recebe um conjunto ordenado de vértices de caminho dentro de um objeto PathElevationRequest. Para solicitar elevações ao longo de caminhos, também é necessário passar um parâmetro indicando quantas amostras você quer obter ao longo desses caminhos.

Todos os métodos devem também passar um método de retorno de chamada para processar os objetos retornados ElevationResult e ElevationStatus.

Solicitações de elevação de localização

Um literal de objeto LocationElevationRequest contém o seguinte campo:

{
  locations[]: LatLng
}

locations (obrigatório) define localizações no planeta sobre as quais retornar dados de elevação. Esse parâmetro aceita uma matriz de LatLngs.

Você pode passar quantas coordenadas quiser em uma matriz, desde que não exceda as cotas do serviço. Observe que, ao passar 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.

Solicitações de elevação de caminho amostradas

Um literal de objeto PathElevationRequest contém os seguintes campos:

{
  path[]: LatLng,
  samples: Number
}

Esses campos são explicados a seguir:

  • path (obrigatório) define um caminho no planeta para o qual são retornados dados de elevação. O parâmetro path define um conjunto de um ou mais pares ordenados de {latitude,longitude} usando uma matriz de dois ou mais objetos LatLng.
  • 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 fornecido em um conjunto ordenado de pontos equidistantes ao longo do caminho.

Da mesma forma que nas solicitações posicionais, o parâmetro path especifica um conjunto 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 nos vértices, as solicitações de caminho são amostradas ao longo do comprimento do caminho. Cada amostra é equidistante das demais (inclusive dos pontos de partida e chegada).

Respostas de Elevation

Para cada solicitação válida, o serviço Elevation retorna para o retorno de chamada especificado um conjunto de objetos ElevationResult, juntamente com um objeto ElevationStatus.

Status de elevação

Cada solicitação de elevação retorna um código ElevationStatus em sua função de retorno de chamada. Esse código de status contém um dos valores a seguir:

  • OK indicando que a solicitação de serviços foi bem-sucedida
  • INVALID_REQUEST indicando que a solicitação de serviço é inválida
  • OVER_QUERY_LIMIT indicando que o solicitante excedeu a cota
  • REQUEST_DENIED indicando que o serviço não concluiu a solicitação, provavelmente devido a um parâmetro inválido
  • UNKNOWN_ERROR indicando um erro desconhecido

Verifique se esse código de status tem um OK atribuído para confirmar que o retorno de chamada funcionou.

Resultados de Elevation

Se a chamada for bem-sucedida, o argumento results da função de retorno de chamada conterá um conjunto de objetos ElevationResult. Esses objetos contêm os seguintes elementos:

  • Um elemento location (contendo objetos LatLng) da posição para a qual os dados de elevação são calculados. Observe que, para solicitações de caminho, o conjunto de elementos de location contém os pontos de amostra ao longo do caminho.
  • Um elemento elevation indicando a elevação da localização em metros.
  • Um valor resolution, indicando a distância máxima entre os pontos de dados entre os quais a elevação foi interpolada, em metros. Essa propriedade não estará presente se a resolução for desconhecida. Observe que os dados de elevação se tornam mais imprecisos (valores maiores de resolution) quando vários pontos são passados. Para obter o valor de elevação mais preciso para um ponto, é necessário fazer a consulta separadamente.

Exemplos de elevação

O código a seguir converte um clique no mapa em uma solicitação de elevação usando o objeto LocationElevationRequest:

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 8,
    center: {lat: 63.333, lng: -150.5},  // Denali.
    mapTypeId: 'terrain'
  });
  var elevator = new google.maps.ElevationService;
  var infowindow = new google.maps.InfoWindow({map: map});

  // Add a listener for the click event. Display the elevation for the LatLng of
  // the click inside the infowindow.
  map.addListener('click', function(event) {
    displayLocationElevation(event.latLng, elevator, infowindow);
  });
}

function displayLocationElevation(location, elevator, infowindow) {
  // Initiate the location request
  elevator.getElevationForLocations({
    'locations': [location]
  }, function(results, status) {
    infowindow.setPosition(location);
    if (status === 'OK') {
      // Retrieve the first result
      if (results[0]) {
        // Open the infowindow indicating the elevation at the clicked position.
        infowindow.setContent('The elevation at this point <br>is ' +
            results[0].elevation + ' meters.');
      } else {
        infowindow.setContent('No results found');
      }
    } else {
      infowindow.setContent('Elevation service failed due to: ' + status);
    }
  });
}
<div id="map"></div>
/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 8,
    center: {lat: 63.333, lng: -150.5},  // Denali.
    mapTypeId: 'terrain'
  });
  var elevator = new google.maps.ElevationService;
  var infowindow = new google.maps.InfoWindow({map: map});

  // Add a listener for the click event. Display the elevation for the LatLng of
  // the click inside the infowindow.
  map.addListener('click', function(event) {
    displayLocationElevation(event.latLng, elevator, infowindow);
  });
}

function displayLocationElevation(location, elevator, infowindow) {
  // Initiate the location request
  elevator.getElevationForLocations({
    'locations': [location]
  }, function(results, status) {
    infowindow.setPosition(location);
    if (status === 'OK') {
      // Retrieve the first result
      if (results[0]) {
        // Open the infowindow indicating the elevation at the clicked position.
        infowindow.setContent('The elevation at this point <br>is ' +
            results[0].elevation + ' meters.');
      } else {
        infowindow.setContent('No results found');
      }
    } else {
      infowindow.setContent('Elevation service failed due to: ' + status);
    }
  });
}

Ver o exemplo (elevation-simple.html).

O exemplo a seguir constrói uma polilinha com base em um conjunto de coordenadas específicas e exibe dados de elevação ao longo do caminho usando a Google Visualization API. (É necessário carregar essa API usando o Google Common Loader.) Uma solicitação de elevação é construída usando PathElevationRequest:

// Load the Visualization API and the columnchart package.
google.load('visualization', '1', {packages: ['columnchart']});

function initMap() {
  // The following path marks a path from Mt. Whitney, the highest point in the
  // continental United States to Badwater, Death Valley, the lowest point.
  var path = [
      {lat: 36.579, lng: -118.292},  // Mt. Whitney
      {lat: 36.606, lng: -118.0638},  // Lone Pine
      {lat: 36.433, lng: -117.951},  // Owens Lake
      {lat: 36.588, lng: -116.943},  // Beatty Junction
      {lat: 36.34, lng: -117.468},  // Panama Mint Springs
      {lat: 36.24, lng: -116.832}];  // Badwater, Death Valley

  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 8,
    center: path[1],
    mapTypeId: 'terrain'
  });

  // Create an ElevationService.
  var elevator = new google.maps.ElevationService;

  // Draw the path, using the Visualization API and the Elevation service.
  displayPathElevation(path, elevator, map);
}

function displayPathElevation(path, elevator, map) {
  // Display a polyline of the elevation path.
  new google.maps.Polyline({
    path: path,
    strokeColor: '#0000CC',
    strokeOpacity: 0.4,
    map: map
  });

  // Create a PathElevationRequest object using this array.
  // Ask for 256 samples along that path.
  // Initiate the path request.
  elevator.getElevationAlongPath({
    'path': path,
    'samples': 256
  }, plotElevation);
}

// Takes an array of ElevationResult objects, draws the path on the map
// and plots the elevation profile on a Visualization API ColumnChart.
function plotElevation(elevations, status) {
  var chartDiv = document.getElementById('elevation_chart');
  if (status !== 'OK') {
    // Show the error code inside the chartDiv.
    chartDiv.innerHTML = 'Cannot show elevation: request failed because ' +
        status;
    return;
  }
  // Create a new chart in the elevation_chart DIV.
  var chart = new google.visualization.ColumnChart(chartDiv);

  // Extract the data from which to populate the chart.
  // Because the samples are equidistant, the 'Sample'
  // column here does double duty as distance along the
  // X axis.
  var data = new google.visualization.DataTable();
  data.addColumn('string', 'Sample');
  data.addColumn('number', 'Elevation');
  for (var i = 0; i < elevations.length; i++) {
    data.addRow(['', elevations[i].elevation]);
  }

  // Draw the chart using the data within its DIV.
  chart.draw(data, {
    height: 150,
    legend: 'none',
    titleY: 'Elevation (m)'
  });
}
<div>
  <div id="map" style="height:250px;"></div>
  <div id="elevation_chart"></div>
</div>
/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
<script src="https://www.google.com/jsapi"></script>
 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
// Load the Visualization API and the columnchart package.
google.load('visualization', '1', {packages: ['columnchart']});

function initMap() {
  // The following path marks a path from Mt. Whitney, the highest point in the
  // continental United States to Badwater, Death Valley, the lowest point.
  var path = [
      {lat: 36.579, lng: -118.292},  // Mt. Whitney
      {lat: 36.606, lng: -118.0638},  // Lone Pine
      {lat: 36.433, lng: -117.951},  // Owens Lake
      {lat: 36.588, lng: -116.943},  // Beatty Junction
      {lat: 36.34, lng: -117.468},  // Panama Mint Springs
      {lat: 36.24, lng: -116.832}];  // Badwater, Death Valley

  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 8,
    center: path[1],
    mapTypeId: 'terrain'
  });

  // Create an ElevationService.
  var elevator = new google.maps.ElevationService;

  // Draw the path, using the Visualization API and the Elevation service.
  displayPathElevation(path, elevator, map);
}

function displayPathElevation(path, elevator, map) {
  // Display a polyline of the elevation path.
  new google.maps.Polyline({
    path: path,
    strokeColor: '#0000CC',
    strokeOpacity: 0.4,
    map: map
  });

  // Create a PathElevationRequest object using this array.
  // Ask for 256 samples along that path.
  // Initiate the path request.
  elevator.getElevationAlongPath({
    'path': path,
    'samples': 256
  }, plotElevation);
}

// Takes an array of ElevationResult objects, draws the path on the map
// and plots the elevation profile on a Visualization API ColumnChart.
function plotElevation(elevations, status) {
  var chartDiv = document.getElementById('elevation_chart');
  if (status !== 'OK') {
    // Show the error code inside the chartDiv.
    chartDiv.innerHTML = 'Cannot show elevation: request failed because ' +
        status;
    return;
  }
  // Create a new chart in the elevation_chart DIV.
  var chart = new google.visualization.ColumnChart(chartDiv);

  // Extract the data from which to populate the chart.
  // Because the samples are equidistant, the 'Sample'
  // column here does double duty as distance along the
  // X axis.
  var data = new google.visualization.DataTable();
  data.addColumn('string', 'Sample');
  data.addColumn('number', 'Elevation');
  for (var i = 0; i < elevations.length; i++) {
    data.addRow(['', elevations[i].elevation]);
  }

  // Draw the chart using the data within its DIV.
  chart.draw(data, {
    height: 150,
    legend: 'none',
    titleY: 'Elevation (m)'
  });
}

Ver o exemplo (elevation-paths.html).

Enviar comentários sobre…

Google Maps JavaScript API
Google Maps JavaScript API
Precisa de ajuda? Acesse nossa página de suporte.