Servicio Elevation

Descripción general

El servicio Elevation proporciona datos de elevación para ubicaciones sobre la superficie de la Tierra, incluidas determinadas áreas del fondo marino (para las cuales se muestran valores negativos). En los casos en que Google no cuente con mediciones de elevación exactas para la ubicación precisa de tu solicitud, el servicio realizará una interpolación y mostrará un valor promediado basado en las cuatro ubicaciones más cercanas.

El objeto ElevationService te proporciona una interfaz sencilla para realizar consultas sobre ubicaciones de la Tierra y obtener datos acerca de la elevación. También puedes solicitar datos de elevación muestreados para las rutas a fin de calcular los cambios de elevación equidistantes correspondientes. El objeto ElevationService se comunica con el servicio Elevation de la API de Google Maps, que recibe solicitudes de elevación y muestra datos de elevación.

Con el servicio Elevation, puedes desarrollar aplicaciones de caminatas y recorridos en bicicleta, de posicionamiento móvil o de encuestas en baja resolución.

Cómo comenzar

Antes de usar el servicio Elevation en la API de Maps JavaScript, asegúrate de que la API de Elevation esté habilitada en la consola de Google Cloud, en el mismo proyecto que configuraste para la API de Maps JavaScript.

Para ver tu lista de APIs habilitadas, haz lo siguiente:

  1. Ve a la consola de Google Cloud.
  2. Haz clic en el botón Seleccionar un proyecto, selecciona el mismo proyecto que configuraste para la API de Maps JavaScript y haz clic en Abrir.
  3. En la lista de APIs del Panel, busca API de Elevation.
  4. Si ves la API en la lista, no necesitas hacer nada más. Si la API no está en la lista, habilítala:
    1. En la parte superior de la página, selecciona HABILITAR API para abrir la pestaña Biblioteca. También puedes seleccionar Biblioteca en el menú lateral izquierdo.
    2. Busca API de Elevation y selecciónala en la lista de resultados.
    3. Selecciona HABILITAR. Cuando finalice el proceso, la API de Elevation aparecerá en la lista de APIs del Panel.

Precios y políticas

Precios

El 16 de julio de 2018, entró en vigencia un nuevo plan de precios de pago por uso para Maps, Routes y Places. Para obtener más información sobre los nuevos precios y límites de uso del servicio Elevation de JavaScript, consulta Uso y facturación para la API de Elevation.

Políticas

El servicio Elevation se debe utilizar conforme a las políticas que se describen para la API de Elevation.

Solicitudes de Elevation

El acceso al servicio Elevation es asíncrono, ya que la API de Google Maps debe realizar una llamada a un servidor externo. Por ese motivo, debes pasar un método de devolución de llamada para la ejecución una vez que se complete la solicitud. Este método de devolución de llamada debe procesar el resultado. Ten en cuenta que el servicio Elevation muestra un código de estado (ElevationStatus) y un array de objetos ElevationResult separados.

ElevationService controla dos tipos de solicitudes:

  • Solicitudes de ubicaciones discretas independientes con el método getElevationForLocations(), al que se le pasa una lista de una o varias ubicaciones mediante un objeto LocationElevationRequest
  • Solicitudes de elevación en una serie de puntos conectados de una ruta mediante el método getElevationAlongPath(), al que se le pasa un conjunto ordenado de vértices de ruta dentro de un objeto PathElevationRequest Al solicitar elevaciones en rutas, también debes pasar un parámetro que indique la cantidad de muestras que deseas tomar en dicha ruta.

Cada uno de estos métodos también debe pasar un método de devolución de llamada para administrar los objetos ElevationResult y ElevationStatus que se muestran.

Solicitudes de ubicación de Elevation

El literal de objeto LocationElevationRequest contiene el siguiente campo:

{
  locations[]: LatLng
}

locations (obligatorio) define las ubicaciones de la Tierra a partir de las cuales se muestran los datos de elevación. Este parámetro toma un array de LatLng.

Puedes pasar cualquier cantidad de coordenadas en un array, siempre que no excedas las cuotas de servicio. Ten en cuenta que, cuando se pasan varias coordenadas, la precisión de los datos resultantes puede ser inferior que cuando se solicitan datos para una única coordenada.

Solicitudes de rutas muestreadas de Elevation

El literal de objeto PathElevationRequest contiene los siguientes campos:

{
  path[]: LatLng,
  samples: Number
}

Estos campos se explican a continuación:

  • path (obligatorio): Define una ruta en el Tierra para la cual se deben mostrar datos de elevación. El parámetro path define un conjunto de dos o más pares de coordenadas (latitud y longitud) mediante un array de dos o más objetos LatLng.
  • samples (obligatorio): Especifica la cantidad de puntos de muestra a lo largo de una ruta para la que se muestran datos de elevación. El parámetro samples divide el objeto path determinado en un conjunto ordenado de puntos equidistantes a lo largo de la ruta.

Al igual que con las solicitudes posicionales, el parámetro path especifica un conjunto de valores de latitud y longitud. Sin embargo, a diferencia de una solicitud posicional, la path especifica un conjunto ordenado de vértices. En lugar de mostrar los datos de elevación en los vértices, las solicitudes de ruta se muestrean a lo largo de la ruta, donde cada muestra es equidistante entre sí (incluidos los extremos).

Respuestas de Elevation

Para cada solicitud válida, el servicio Elevation responde a la función de devolución de llamada un conjunto de objetos ElevationResult y un objeto ElevationStatus.

Estados de Elevation

Cada solicitud de Elevation muestra un código ElevationStatus en su función de devolución de llamada. Este código status contiene uno de los siguientes valores:

  • OK: Indica que la solicitud de servicio se realizó correctamente.
  • INVALID_REQUEST: Indica que la solicitud de servicio tiene un formato incorrecto.
  • OVER_QUERY_LIMIT: Indica que el solicitante superó la cuota.
  • REQUEST_DENIED: Indica que el servicio no completó la solicitud, probablemente, debido a un parámetro no válido.
  • UNKNOWN_ERROR: Indica un error desconocido.

Examina este código de estado para OK a fin de comprobar que la devolución de llamada se haya realizado correctamente.

Resultados de Elevation

Si la solicitud es exitosa, el argumento results de la función de devolución de llamada contendrá un conjunto de objetos ElevationResult. Estos objetos contienen los siguientes elementos:

  • Un elemento location (con objetos LatLng) de la posición para la que se calculan los datos de elevación (ten en cuenta que, para las solicitudes de ruta, el conjunto de elementos location contendrá los puntos de muestreo a lo largo de la ruta)
  • Un elemento elevation que indica la elevación de la ubicación en metros
  • Un valor de resolution que indica la distancia máxima en metros entre los puntos de datos a partir de los cuales se interpoló la elevación. Esta propiedad estará ausente si se desconoce la resolución. Ten en cuenta que los datos de elevación se vuelven menos precisos (valores de resolution mayores) cuando se pasan varios puntos. Para obtener el valor de elevación más preciso para un punto, se deben realizar consultas independientes

Ejemplos de Elevation

El siguiente código convierte un clic en un mapa en una solicitud de elevación mediante el 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
Ver ejemplo

Prueba la muestra

En el siguiente ejemplo, se crea una polilínea a partir de un conjunto de coordenadas y se muestran los datos de elevación de la ruta por medio de la API de visualización de Google. (debes cargar esta API a través del cargador común de Google). Luego, se crea una solicitud de elevación con 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
Ver ejemplo

Prueba la muestra