Serviço Elevation

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Visão geral

O serviço Elevation fornece dados de elevação para locais na superfície terrestre, incluindo locais em profundidade no fundo do oceano, que retornam valores negativos. Nos casos em que o Google não tem medidas de elevação exatas no local exato solicitado, o serviço interpola e retorna um valor médio usando os quatro locais mais próximos.

O objeto ElevationService fornece uma interface simples para consultar dados no Google Earth sobre dados de elevação. Além disso, você pode solicitar dados de elevação com amostragem nos caminhos, permitindo calcular as mudanças de elevação equidistantes nos trajetos. O objeto ElevationService se comunica com o serviço de elevação da API Google Maps, que recebe solicitações de elevação e retorna dados de elevação.

Com o serviço de elevação, é possível desenvolver aplicativos de caminhada e ciclismo, aplicativos de posicionamento para dispositivos móveis ou aplicativos de pesquisa de baixa resolução.

Primeiros passos

Antes de usar o serviço Elevation na API Maps JavaScript, verifique se ela está ativada no Console do Google Cloud, no mesmo projeto que você configurou para a API Maps JavaScript.

Para ver a lista de APIs ativadas:

  1. Acesse o Console do Google Cloud.
  2. Clique no botão Selecionar um projeto, escolha o mesmo projeto configurado para a API Maps JavaScript e clique em Abrir.
  3. Na lista de APIs no Painel, procure API Elevation.
  4. Se achar a API na lista, está tudo pronto. Se a API não estiver listada, ative-a:
    1. Na parte superior da página, selecione ATIVAR API para exibir a guia Biblioteca. Como alternativa, no menu lateral à esquerda, selecione Biblioteca.
    2. Pesquise API Elevation e selecione-a na lista de resultados.
    3. Selecione ATIVAR. Quando o processo for concluído, a API Elevation 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 utilização entrou em vigor para o Maps, Routes e Places. Para saber mais sobre os novos limites de preço e uso para o uso do serviço JavaScript Elevation, consulte Uso e faturamento para a API Elevation.

Limites de taxas

Observações sobre os limites de taxa em solicitações adicionais:

A limitação de taxa é aplicada por sessão de usuário, independentemente de quantos usuários compartilham o mesmo projeto. Ao carregar a API pela primeira vez, você recebe uma cota inicial de solicitações. Depois de usar essa cota, a API aplica limites de taxa em outras solicitações por segundo. Se muitas solicitações forem feitas em um determinado período, a API retornará um código de resposta OVER_QUERY_LIMIT.

A limitação da taxa por sessão impede o uso de serviços do lado do cliente para solicitações em lote. Se você quiser calcular elevações para locais conhecidos e estáticos, use o serviço da Web da API Elevation.

Políticas

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

Solicitações de Elevation

O acesso ao serviço de elevação é assíncrono, porque a API Google Maps precisa fazer uma chamada para um servidor externo. Por isso, é necessário transmitir um método de callback para ser executado após a conclusão da solicitação. Esse método de callback precisa processar os resultados. O serviço de elevação retorna um código de status (ElevationStatus) e uma matriz de objetos ElevationResult separados.

O ElevationService processa dois tipos de solicitações:

  • Solicitações para locais separados e distintos usando o método getElevationForLocations(), que recebe uma lista de um ou mais locais usando um objeto LocationElevationRequest.
  • Solicitações para elevação em 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. Ao solicitar elevações ao longo de caminhos, você também precisa enviar um parâmetro indicando quantas amostras quer usar nesse caminho.

Cada um desses métodos também precisa transmitir um método de callback para processar 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 os locais na Terra sobre os quais os dados de elevação serão retornados. Esse 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. Ao transmitir várias coordenadas, a precisão dos dados retornados pode ter uma resolução menor do que ao solicitar dados de uma única coordenada.

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

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

{
  path[]: LatLng,
  samples: Number
}

Estes campos são explicados abaixo:

  • path (obrigatório) define um caminho no planeta sobre o qual retornar dados de elevação. O parâmetro path define um conjunto de dois 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 em um caminho para o qual dados de elevação serão retornados. O parâmetro samples divide o path especificado em um conjunto ordenado de pontos equidistantes ao longo do caminho.

Assim como nas solicitações posicionais, o parâmetro path especifica um conjunto de valores de latitude e longitude. Ao contrário das solicitações posicionais, 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 usadas em amostra ao longo do caminho, em que cada amostra é equidistante uma da outra (incluindo os endpoints).

Respostas de Elevation

Para cada solicitação válida, o Serviço de elevação retornará ao retorno de chamada definido um conjunto de objetos ElevationResult com um objeto ElevationStatus.

Status de elevação

Cada solicitação de elevação retorna um código ElevationStatus dentro da função de callback. Esse código status conterá um dos seguintes valores:

  • OK: indica que a solicitação do serviço foi realizada corretamente
  • INVALID_REQUEST indicando que a solicitação de serviço estava incorreta
  • OVER_QUERY_LIMIT indica que o solicitante excedeu a cota
  • REQUEST_DENIED indica que o serviço não concluiu a solicitação, provavelmente devido a um parâmetro inválido
  • UNKNOWN_ERROR: indica um erro desconhecido

Verifique se o retorno de chamada foi bem-sucedido examinando este código de status de OK.

Resultados de Elevation

Após o sucesso, o argumento results da função de callback 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 estão sendo calculados. Para solicitações de caminho, o conjunto de elementos location conterá os pontos de amostragem ao longo do caminho.
  • Um elemento elevation que indica a elevação do local em metros.
  • Um valor resolution, que indica a distância máxima entre pontos de dados em que a elevação foi interpolada, em metros. Esta propriedade estará ausente se a resolução for desconhecida. Os dados de elevação se tornam mais abrangentes (valores resolution maiores) quando vários pontos são transmitidos. Para saber o valor da elevação mais precisa de um ponto, ele precisa ser consultado de forma independente.

Exemplos de elevação

O código a seguir converte um clique em um 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;

JavaScript

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: { lat: 63.333, lng: -150.5 },
    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;
Ver exemplo

Testar amostra

O exemplo a seguir constrói uma polilinha com base em um conjunto de coordenadas e exibe dados de elevação ao longo do caminho usando a API Google Preview. Carregue essa API usando o carregador comum do Google. Uma solicitação de elevação é criada usando o 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;

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 },
    { lat: 36.606, lng: -118.0638 },
    { lat: 36.433, lng: -117.951 },
    { lat: 36.588, lng: -116.943 },
    { lat: 36.34, lng: -117.468 },
    { 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;
Ver exemplo

Testar amostra