Service Elevation

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

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 des données de profondeur au niveau de l'océan (qui renvoient des valeurs négatives). Dans les cas où Google ne dispose pas des mesures d'altitude exactes du point géographique précis que vous demandez, le service procède à une interpolation et renvoie une valeur moyenne basée sur les quatre emplacements 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. En outre, vous pouvez demander des données d'altitude échantillonnées sur les chemins, ce qui vous permet de calculer les changements d'altitude équidistants le long des itinéraires. L'objet ElevationService communique avec le service Elevation de Google Maps, qui reçoit des requêtes d'altitude et renvoie des données d'altitude.

Avec le service Elevation, vous pouvez développer des applications de randonnée et de vélo, des applications de positionnement mobile ou de géolocalisation basse résolution.

Premiers pas

Avant d'utiliser le service Elevation dans l'API Maps JavaScript, assurez-vous qu'elle est activée dans Google Cloud Console, dans le même projet que celui que vous avez configuré pour l'API Maps JavaScript.

Pour afficher la liste des API activées :

  1. Accédez à Google Cloud Console.
  2. Cliquez sur le bouton Sélectionner un projet, puis sélectionnez le projet que vous avez configuré pour l'API Maps JavaScript et cliquez sur Ouvrir.
  3. Dans la liste des API du tableau de bord, recherchez 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 Elevation API, puis sélectionnez-le dans la liste des résultats.
    3. Sélectionnez ACTIVER. Une fois le processus terminé, API Elevation apparaît dans la liste des API du tableau de bord.

Tarifs et règles

Tarifs

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

Limites de débit

Veuillez noter les points suivants concernant les limites de débit pour les requêtes supplémentaires:

La limite de débit est appliquée par session utilisateur, quel que soit le nombre d'utilisateurs qui partagent le même projet. Lorsque vous chargez l'API pour la première fois, un quota initial de requêtes vous est attribué. Une fois que vous avez utilisé ce quota, l'API applique des limites de débit à d'autres requêtes par seconde. Si trop de requêtes sont effectuées dans un délai donné, l'API renvoie un code de réponse OVER_QUERY_LIMIT.

La limite de débit par session empêche l'utilisation de services côté client pour les requêtes par lot. Si vous souhaitez calculer des altitudes pour des lieux statiques et connus, utilisez le service Web 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

L'accès au service Elevation est asynchrone, car l'API Google Maps doit appeler un serveur externe. Pour cette raison, vous devez transmettre une méthode de rappel à exécuter une fois la requête terminée. 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:

  • Requêtes pour des emplacements distincts et distincts à l'aide de la méthode getElevationForLocations(), qui reçoit la liste d'un ou plusieurs établissements à l'aide d'un objet LocationElevationRequest.
  • Requêtes d'élévation sur une série de points connectés le long du chemin à l'aide de la méthode getElevationAlongPath(), qui est transmise par un ensemble ordonné de sommets de tracé dans un objet PathElevationRequest. Lorsque vous demandez des élévations le long d'un trajet, vous devez également transmettre un paramètre indiquant le nombre d'échantillons à emprunter.

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 points géographiques sur lesquels la Terre doit renvoyer des données d'altitude. Ce paramètre accepte un tableau de LatLng.

Vous pouvez transmettre autant de coordonnées que vous le souhaitez dans un tableau, à condition de ne pas dépasser les quotas de service. Notez que lorsque vous transmettez plusieurs coordonnées, la précision des données renvoyées peut être inférieure à celle d'une requête de données pour une coordonnée.

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

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

{
  path[]: LatLng,
  samples: Number
}

Expliquons chacun de ces champs :

  • path (obligatoire) définit un tracé sur Terre pour lequel afficher 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 d'au moins deux objets LatLng.
  • samples (obligatoire) spécifie le nombre d'échantillons de points 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 positionnelles, le paramètre path spécifie un ensemble de valeurs de latitude et de longitude. Toutefois, contrairement à une requête positionnelle, 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 sur la longueur du trajet, où chaque échantillon est équidistant les uns des autres (en tenant compte des points de terminaison).

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 avec 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, indiquant que la requête de service a abouti
  • INVALID_REQUEST, indiquant que la requête de service n'était pas valide
  • OVER_QUERY_LIMIT indique que le demandeur a dépassé le quota
  • REQUEST_DENIED indiquant que le service n'a pas terminé la requête, probablement en raison d'un paramètre non valide.
  • UNKNOWN_ERROR indiquant une erreur inconnue

Vous devez vérifier que votre rappel a réussi en examinant ce code d'état pour OK.

Résultats d'altitude

En cas de réussite, l'argument results de votre fonction de rappel contient un ensemble d'objets ElevationResult. Chaque objet contient les éléments suivants :

  • Élément location (contenant LatLng objets) de la position pour laquelle les données d'altitude sont calculées. Notez que pour les requêtes de chemin, 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.
  • 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é sera manquante si la résolution n'est pas connue. Notez que les données d'altitude deviennent plus approximatives (valeurs resolution plus élevées) lorsque plusieurs points sont transmis. Pour obtenir la valeur d'altitude la plus précise possible pour un point, celui-ci doit être interrogé indépendamment.

Exemples d'altitude

Le code suivant traduit un clic sur une carte en une requête d'élévation à 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;

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;
Voir un 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 Visualisation. (Vous devez charger cette API à l'aide de Google Common Charger.) Une requête d'altitude est construite à l'aide de 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;
Voir un exemple

Essayer l'exemple