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 as profundezas 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 fornece uma interface simples para consultas de locais na Terra e obtenção de dados de elevação. 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 API Google Maps, que recebe solicitações de elevação e retorna dados relacionados.

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.

Começar

Antes de usar o serviço Elevation na API Maps JavaScript, verifique se a API Elevation está ativada no console do Google Cloud, no mesmo projeto configurado para a API Maps JavaScript.

Para saber quais são as APIs ativadas:

  1. Acesse o console do Google Cloud.
  2. Clique no botão Selecionar um projeto, escolha o que você configurou para a API Maps JavaScript e selecione Abrir.
  3. Na lista de APIs do Painel, procure API Elevation.
  4. Se achar a API na lista, pode prosseguir. Caso contrário, faça o seguinte para ativar a API:
    1. Na parte de cima da página, selecione ATIVAR API para abrir a guia Biblioteca. Outra opção é selecionar Biblioteca no menu lateral esquerdo.
    2. Pesquise e selecione API Elevation na lista de resultados.
    3. Clique em ATIVAR. Quando o processo terminar, a API Elevation vai aparecer na lista de APIs do Painel.

Preços e políticas

Preços

Em 16 de julho de 2018, um novo plano de pagamento por uso entrou em vigor para o Maps, Routes e Places. Se quiser saber mais sobre os novos limites de preço e uso do serviço JavaScript Elevation, consulte Utilização e faturamento referente à API Elevation.

Políticas

O uso do serviço Elevation precisa estar de acordo com as políticas da API Elevation.

Solicitações do Elevation

O acesso ao serviço Elevation é assíncrono porque a API Google Maps precisa chamar um servidor externo. Por isso, você precisa transmitir um método de callback que vai ser executado quando a solicitação for concluída. Esse método de callback processa os resultados. O serviço Elevation retorna um código de status (ElevationStatus) e uma matriz de objetos ElevationResult diferentes.

O ElevationService suporta dois tipos de solicitações:

  • Solicitações para locais diferentes e específicos usando o método getElevationForLocations(), que recebe uma lista de um ou mais locais usando um objeto LocationElevationRequest.
  • Solicitações para elevação em vários 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 ao longo deles.

Cada um desses métodos também passa um método de callback para manipular os objetos ElevationResult e ElevationStatus retornados.

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

Um literal do 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. Este parâmetro usa uma matriz de LatLngs.

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

Solicitações de caminho do Elevation com amostragem

Um literal do 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 que são retornados dados de elevação. O parâmetro path define um conjunto de dois ou mais pares (latitude, longitude) ordenados 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 especificado em um conjunto ordenado de pontos equidistantes ao longo do caminho.

Assim como ocorre com as solicitações posicionais, 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 nos vértices, as solicitações de caminho são amostradas ao longo do comprimento do caminho. Cada amostra é equidistante das demais (inclusive dos endpoints).

Respostas do Elevation

Para cada solicitação válida, o serviço Elevation retorna para o callback definido um conjunto de objetos ElevationResult, além de um objeto ElevationStatus.

Status do Elevation

Cada solicitação de elevação retorna um código ElevationStatus na sua função de callback. Esse código status vai conter um dos seguintes valores:

  • OK: indicando que a solicitação de serviços funcionou
  • INVALID_REQUEST: indicando que a solicitação do 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 o funcionamento do callback.

Resultados do Elevation

Se a chamada funcionar, o argumento results da função de callback vai conter um conjunto de objetos ElevationResult. Esses objetos contêm os seguintes elementos:

  • Um elemento location (contendo objetos LatLng) da posição para que os dados de elevação são calculados. Para solicitações de caminho, o conjunto de elementos 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 vai estar presente se a resolução for desconhecida. Os dados de elevação ficam mais imprecisos (valores maiores de resolution) 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.

Exemplos do Elevation

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

TypeScript

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

  infowindow.open(map);

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

function displayLocationElevation(
  location: google.maps.LatLng,
  elevator: google.maps.ElevationService,
  infowindow: google.maps.InfoWindow
) {
  // Initiate the location request
  elevator
    .getElevationForLocations({
      locations: [location],
    })
    .then(({ results }) => {
      infowindow.setPosition(location);

      // 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");
      }
    })
    .catch((e) =>
      infowindow.setContent("Elevation service failed due to: " + e)
    );
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

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

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

function displayLocationElevation(location, elevator, infowindow) {
  // Initiate the location request
  elevator
    .getElevationForLocations({
      locations: [location],
    })
    .then(({ results }) => {
      infowindow.setPosition(location);
      // 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");
      }
    })
    .catch((e) =>
      infowindow.setContent("Elevation service failed due to: " + e),
    );
}

window.initMap = initMap;
index.js
Exemplo

Testar amostra

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

TypeScript

// Load the Visualization API and the columnchart package.
// @ts-ignore TODO update to newest visualization library
google.load("visualization", "1", { packages: ["columnchart"] });

function initMap(): void {
  // The following path marks a path from Mt. Whitney, the highest point in the
  // continental United States to Badwater, Death Valley, the lowest point.
  const 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

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

  // Create an ElevationService.
  const elevator = new google.maps.ElevationService();

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

function displayPathElevation(
  path: google.maps.LatLngLiteral[],
  elevator: google.maps.ElevationService,
  map: google.maps.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,
    })
    .then(plotElevation)
    .catch((e) => {
      const chartDiv = document.getElementById(
        "elevation_chart"
      ) as HTMLElement;

      // Show the error code inside the chartDiv.
      chartDiv.innerHTML = "Cannot show elevation: request failed because " + e;
    });
}

// Takes an array of ElevationResult objects, draws the path on the map
// and plots the elevation profile on a Visualization API ColumnChart.
function plotElevation({ results }: google.maps.PathElevationResponse) {
  const chartDiv = document.getElementById("elevation_chart") as HTMLElement;

  // Create a new chart in the elevation_chart DIV.
  const 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.
  const data = new google.visualization.DataTable();

  data.addColumn("string", "Sample");
  data.addColumn("number", "Elevation");

  for (let i = 0; i < results.length; i++) {
    data.addRow(["", results[i].elevation]);
  }

  // Draw the chart using the data within its DIV.
  chart.draw(data, {
    height: 150,
    legend: "none",
    // @ts-ignore TODO update to newest visualization library
    titleY: "Elevation (m)",
  });
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

// Load the Visualization API and the columnchart package.
// @ts-ignore TODO update to newest visualization library
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.
  const 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
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: path[1],
    mapTypeId: "terrain",
  });
  // Create an ElevationService.
  const 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,
    })
    .then(plotElevation)
    .catch((e) => {
      const chartDiv = document.getElementById("elevation_chart");

      // Show the error code inside the chartDiv.
      chartDiv.innerHTML = "Cannot show elevation: request failed because " + e;
    });
}

// Takes an array of ElevationResult objects, draws the path on the map
// and plots the elevation profile on a Visualization API ColumnChart.
function plotElevation({ results }) {
  const chartDiv = document.getElementById("elevation_chart");
  // Create a new chart in the elevation_chart DIV.
  const 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.
  const data = new google.visualization.DataTable();

  data.addColumn("string", "Sample");
  data.addColumn("number", "Elevation");

  for (let i = 0; i < results.length; i++) {
    data.addRow(["", results[i].elevation]);
  }

  // Draw the chart using the data within its DIV.
  chart.draw(data, {
    height: 150,
    legend: "none",
    // @ts-ignore TODO update to newest visualization library
    titleY: "Elevation (m)",
  });
}

window.initMap = initMap;
index.js
Exemplo

Testar amostra

JSFiddle.net (link em inglês) Google Cloud Shell