Service Elevation

Présentation

Le service Elevation fournit des données d'altitude pour des points géographiques situés à la surface de la Terre, y compris les fonds océaniques (lesquels renvoient des valeurs négatives). Si Google ne dispose pas des mesures d'altitude exactes de la position exacte demandée, le service retourne une valeur d'interpolation moyenne basée sur les quatre points géographiques les plus proches.

L'objet ElevationService fournit une interface simple qui permet d'interroger des emplacements sur Terre pour obtenir des données d'altitude. Vous pouvez également obtenir des données d'altitude échantillonnées le long d'un tracé, afin de calculer les variations d'altitude équidistantes sur un itinéraire. L'objet ElevationService communique avec le service Elevation de l'API Google Maps, qui reçoit les requêtes et renvoie des données d'altitude.

Le service Elevation vous permet de développer des applications de randonnée ou de cyclisme, de géolocalisation mobile, ou encore de topographie basse résolution.

Premiers pas

Avant d'utiliser le service Elevation dans l'API Maps JavaScript, vérifiez que l'API Elevation est activée dans la console Google Cloud, dans le projet que vous avez configuré pour l'API Maps JavaScript.

Pour afficher la liste des API activées :

  1. Accédez à la console Google Cloud.
  2. Cliquez sur le bouton Sélectionner un projet, sélectionnez le projet que vous avez configuré pour l'API Maps JavaScript, puis cliquez sur Ouvrir.
  3. Dans la liste des API du tableau de bord, repérez l'API Elevation.
  4. Si vous trouvez l'API dans la liste, vous pouvez continuer. Si l'API ne figure pas dans la liste, activez-la :
    1. En haut de la page, sélectionnez ACTIVER L'API pour afficher l'onglet Bibliothèque. Vous pouvez également sélectionner Bibliothèque dans le menu de gauche.
    2. Recherchez l'API Elevation, puis sélectionnez-la dans la liste des résultats.
    3. Sélectionnez ACTIVER. Une fois le processus terminé, l'API Elevation apparaît dans la liste des API du tableau de bord.

Tarifs et règles

Tarifs

Le 16 juillet 2018, un nouveau système de paiement à l'usage est entré en vigueur pour les services Maps, Routes et Places. Pour en savoir plus sur les nouveaux tarifs et les nouvelles limites d'utilisation du service JavaScript Elevation, consultez la page Utilisation et facturation de l'API Elevation.

Règles

L'utilisation du service Elevation doit être conforme aux règles décrites pour l'API Elevation.

Requêtes d'altitude

Étant donné que l'API Google Maps doit appeler un serveur externe, l'accès au service Elevation est asynchrone. Pour cette raison, vous devez transmettre une méthode de rappel à exécuter à la fin de la requête. Cette méthode de rappel doit traiter le ou les résultats. Notez que le service Elevation renvoie un code d'état (ElevationStatus) et un tableau d'objets ElevationResult distincts.

ElevationService gère deux types de requêtes :

  • les requêtes pour des emplacements distincts à l'aide de la méthode getElevationForLocations(), qui reçoit une liste d'un ou plusieurs lieux à l'aide d'un objet LocationElevationRequest ;
  • les requêtes d'altitude sur une série de points reliés le long d'un chemin à l'aide de la méthode getElevationAlongPath(), qui reçoit un ensemble ordonné de sommets de tracé dans un objet PathElevationRequest. Lorsque vous demandez des altitudes le long d'un tracé, vous devez également transmettre un paramètre indiquant le nombre d'échantillons à utiliser le long de ce tracé.

Chacune de ces méthodes doit également transmettre une méthode de rappel pour gérer les objets ElevationResult et ElevationStatus renvoyés.

Requêtes d'altitude de point géographique

Un littéral d'objet LocationElevationRequest contient le champ suivant :

{
  locations[]: LatLng
}

locations (obligatoire) définit le ou les lieux sur Terre pour lesquels les données d'altitude doivent être renvoyées. Ce paramètre nécessite un tableau de LatLng.

Vous pouvez insérer autant de coordonnées que vous le souhaitez dans un tableau, tant que vous ne dépassez pas les quotas du service. Notez toutefois qu'en transmettant plusieurs coordonnées à la fois, l'exactitude des données renvoyées peut être moindre que lorsque votre requête ne porte que sur une seule coordonnée.

Requêtes d'altitude de tracé échantillonné

Un littéral d'objet PathElevationRequest contient les champs suivants :

{
  path[]: LatLng,
  samples: Number
}

Ces champs sont décrits ci-dessous :

  • path (obligatoire) définit un tracé sur la Terre pour lequel renvoyer des données d'altitude. Le paramètre path définit un ensemble d'au moins deux paires {latitude,longitude} ordonnées à l'aide d'un tableau comportant au moins deux objets LatLng.
  • samples (obligatoire) spécifie le nombre points échantillonnés le long d'un chemin pour lesquels renvoyer des données d'altitude. Le paramètre samples divise le path donné en un ensemble ordonné de points équidistants le long du chemin.

Comme pour les requêtes de position, le paramètre path spécifie un ensemble de valeurs de latitude et de longitude. Toutefois, contrairement à une requête de position, path spécifie un ensemble ordonné de sommets. Plutôt que de renvoyer des données d'altitude aux sommets, les requêtes de tracé sont échantillonnées le long du trajet, où les échantillons est équidistant des autres (y compris les extrémités).

Réponses aux requêtes d'altitude

Pour chaque requête valide, le service Elevation renvoie au rappel défini un ensemble d'objets ElevationResult et un objet ElevationStatus.

Statuts d'altitude

Chaque requête d'altitude renvoie un code ElevationStatus dans sa fonction de rappel. Ce code status contiendra l'une des valeurs suivantes :

  • OK, qui indique que la requête de service a abouti ;
  • INVALID_REQUEST, qui indique que la requête de service n'a pas été rédigée correctement ;
  • OVER_QUERY_LIMIT, qui indique que le demandeur a dépassé le quota ;
  • REQUEST_DENIED, qui indique que le service n'a pas terminé la requête, probablement en raison d'un paramètre non valide ;
  • UNKNOWN_ERROR, qui indique une erreur inconnue.

Vérifiez que votre rappel a abouti en examinant ce code d'état pour OK.

Résultats d'altitude

S'il aboutit, l'argument results de votre fonction de rappel contient un ensemble d'objets ElevationResult. Chaque objet contient les éléments suivants :

  • Un élément location (contenant des objets LatLng) de la position pour laquelle les données d'altitude sont calculées. Notez que pour les requêtes de tracé, l'ensemble d'éléments location contiendra les points échantillonnés le long du chemin.
  • Un élément elevation indiquant l'altitude du lieu en mètres.
  • Une valeur resolution indiquant la distance maximale, en mètres, entre les points de données à partir desquels l'altitude a été interpolée. Cette propriété est omise si la résolution n'est pas connue. Notez que les données d'altitude sont moins précises (valeurs resolution plus élevées) lorsque plusieurs points sont transmis. Pour obtenir la valeur d'altitude la plus précise possible pour un point, vous devez effectuer une requête indépendante.

Exemples d'altitude

Le code suivant traduit un clic sur une carte en une requête d'altitude à l'aide de l'objet 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
Voir l'exemple

Essayer l'exemple

L'exemple suivant construit une polyligne à partir d'un ensemble de coordonnées et affiche les données d'altitude le long de ce tracé à l'aide de l'API Google Visualization. (Vous devez charger cette API en utilisant Google Common Loader.) Une requête d'altitude est construite à l'aide de la 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
Voir l'exemple

Essayer l'exemple