Servicio de elevación

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Descripción general

El servicio de elevación proporciona datos de elevación para ubicaciones sobre la superficie de la Tierra, incluidas ubicaciones de profundidad sobre el lecho marino (que devuelven valores negativos). En los casos en los que Google no posea medidas de elevación exactas en la ubicación exacta que solicitaste, el servicio interpolará y mostrará un valor promediado usando las cuatro ubicaciones más cercanas.

El objeto ElevationService te proporciona una interfaz simple para consultar ubicaciones en la Tierra en busca de datos de elevación. Además, puedes solicitar datos de elevación de muestra a lo largo de rutas, lo que te permite calcular los cambios de elevación equidistantes en las rutas. El objeto ElevationService se comunica con el servicio de elevación de la API de Google Maps, que recibe solicitudes de elevación y muestra datos de elevación.

Con el servicio de elevación, puedes desarrollar aplicaciones de senderismo y ciclismo, aplicaciones de posicionamiento móvil o aplicaciones de consulta en baja resolución.

Cómo comenzar

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

Para ver tu lista de API habilitadas:

  1. Ve a Google Cloud Console.
  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 API 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 mostrar la pestaña Biblioteca. Como alternativa, en el menú lateral izquierdo, selecciona Biblioteca.
    2. Busca Elevation API y selecciónala en la lista de resultados.
    3. Selecciona HABILITAR. Cuando finalice el proceso, la API de Elevation aparecerá en la lista de API del Panel.

Precios y políticas

Precios

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

Límites de frecuencia

Ten en cuenta lo siguiente sobre los límites de frecuencia para las solicitudes adicionales:

El límite de frecuencia se aplica por sesión de usuario, independientemente de la cantidad de usuarios que compartan el mismo proyecto. Cuando cargas la API por primera vez, se te asigna una cuota inicial de solicitudes. Una vez que usas esta cuota, la API aplica límites de frecuencia sobre las solicitudes adicionales por segundo. Si se realizan demasiadas solicitudes en un período determinado, la API muestra un código de respuesta OVER_QUERY_LIMIT.

El límite de frecuencia por sesión evita el uso de servicios del cliente para solicitudes por lotes. En cambio, si deseas calcular elevaciones de ubicaciones estáticas y conocidas, usa el servicio web de la API de Elevation.

Políticas

El uso del servicio de elevación debe cumplir con las políticas que se describen para la API de Elevation.

Solicitudes de elevación

El acceso al servicio de elevación es asincrónico, ya que la API de Google Maps debe realizar una llamada a un servidor externo. Por ese motivo, debes pasar un método callback para ejecutarlo una vez completada la solicitud. Este método de devolución de llamada debe procesar los resultados. Ten en cuenta que el servicio de elevación muestra un código de estado (ElevationStatus) y un arreglo 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 más ubicaciones mediante un objeto LocationElevationRequest.
  • Solicitudes de elevación en una serie de puntos conectados en una ruta que usa 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 de acceso, también debes pasar un parámetro que indique cuántas muestras deseas tomar en esa ruta de acceso.

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

Solicitudes de elevación de ubicación

El literal de objeto LocationElevationRequest contiene el siguiente campo:

{
  locations[]: LatLng
}

locations (obligatorio) define las ubicaciones terrestres desde las que se deben mostrar datos de elevación. Este parámetro toma un arreglo de LatLng.

Puedes pasar cualquier cantidad de coordenadas múltiples dentro de un arreglo, siempre y cuando no excedas las cuotas de servicio. Ten en cuenta que cuando se pasan coordenadas múltiples, la precisión de los datos mostrados puede ser de menor resolución que cuando se solicitan datos para una única coordenada.

Solicitudes de elevación de rutas de acceso muestreadas

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 planeta para la cual se deben mostrar datos de elevación. El parámetro path define un conjunto de dos o más pares {latitude,longitude} ordenados con un arreglo de dos o más objetos LatLng.
  • samples (obligatorio) especifica la cantidad de puntos de ejemplo 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, el path especifica un conjunto ordenado de vértices. En lugar de mostrar datos de elevación en los vértices, se muestrean solicitudes de ruta a lo largo de la ruta, donde cada muestra es equidistante entre sí (incluidos los extremos).

Respuestas de elevación

Para cada solicitud válida, el servicio de elevación devolverá a la devolución de llamada definida un conjunto de objetos ElevationResult junto con un objeto ElevationStatus.

Estados de elevación

Cada solicitud de elevación muestra un código ElevationStatus dentro de su función de devolución de llamada. Este código status contendrá 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, que 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.

Debes comprobar que la devolución de llamada se realizó correctamente examinando este código de estado para OK.

Resultados de elevación

Si se realiza correctamente, 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 (que contiene 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 desde la que se interpolaron los datos de elevación. Esta propiedad faltará si no se conoce la resolución. Ten en cuenta que los datos de elevación se vuelven más toscos (valores resolution mayores) cuando se pasan varios puntos. Para obtener el valor de elevación más preciso para un punto, se debe consultar de forma independiente.

Ejemplos de elevación

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;

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 ejemplo

Probar la muestra

En el siguiente ejemplo, se construye una polilínea a partir de un conjunto determinado de coordenadas y se muestran datos de elevación de esa ruta mediante la API de visualización de Google. (Debes cargar esta API con el cargador común de Google). 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;

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 ejemplo

Probar la muestra