שירות גבהים

סקירה כללית

שירות הגובה מספק נתוני גובה עבור מיקומים על פני השטח של כדור הארץ, כולל מיקומי עומק בקרקעית האוקיינוס (שמחזירים ערכים שליליים). במקרים שבהם אין ל-Google מדידות מדויקות של גובה במיקום המדויק שביקשת, השירות יבצע אינטרפולציה ויחזיר ערך ממוצע באמצעות ארבעת המיקומים הקרובים.

האובייקט ElevationService מספק ממשק פשוט שמאפשר להריץ שאילתות על מיקומים ב-Earth לקבלת נתוני גובה. בנוסף, אפשר לבקש נתוני גובה שנדגמו לאורך נתיבים, וכך לחשב את שינויי הגובה המקבילים במסלולים. האובייקט ElevationService מתקשר עם שירות גובה ה-API של מפות Google, שמקבל בקשות גובה ושולח נתוני גובה.

בעזרת שירות הגבהה, אפשר לפתח אפליקציות לטיולים רגליים ורכיבה על אופניים, לאפליקציות מיקום לנייד או לאפליקציות סקר ברזולוציה נמוכה.

איך מתחילים

לפני השימוש בשירות Elevation API ב-Maps JavaScript API, יש לוודא ש-Elevation API מופעל במסוף Google Cloud באותו פרויקט שהגדרת ב-Maps JavaScript API.

כדי להציג את הרשימה של ממשקי ה-API שהופעלו:

  1. נכנסים אל מסוף Google Cloud.
  2. לוחצים על הלחצן Select a project, בוחרים את הפרויקט שהגדרתם ב-API של מפות Google ולוחצים על Open.
  3. ברשימת ממשקי ה-API במרכז הבקרה, מחפשים את Elevation API.
  4. אם ה-API מופיע ברשימה, הכול מוכן. אם ה-API לא מופיע, יש להפעיל אותו:
    1. בחלק העליון של הדף בוחרים באפשרות ENABLE API כדי להציג את הכרטיסייה Library. לחלופין, בתפריט הימני לוחצים על Library.
    2. מחפשים את Elevation API ובוחרים אותו מרשימת התוצאות.
    3. לוחצים על הפעלה. בסיום התהליך, Elevation API מופיע ברשימת ממשקי ה-API במרכז הבקרה.

תמחור ומדיניות

תמחור

החל מ-16 ביולי 2018, תוכנית תמחור ותשלומים חדשה לפי שימוש תיכנס לתוקף במפות, בנתיבים ובמקומות. למידע נוסף על מגבלות התמחור והשימוש החדשות בקשר לשימוש בשירות הגבהה של JavaScript, ראו שימוש וחיוב עבור ממשק ה-API של Elevation.

כללי מדיניות

יש להשתמש בשירות Elevation בהתאם למדיניות המתוארת עבור Elevation API.

בקשות גובה

הגישה לשירות גובה היא אסינכרונית, מאחר ש-Google Maps API צריך לבצע קריאה לשרת חיצוני. לכן, עליכם להעביר ל-method callback כדי למלא את הבקשה. שיטת הקריאה החוזרת הזו אמורה לעבד את התוצאות. הערה: שירות הגבהים מחזיר קוד סטטוס (ElevationStatus) ומערך של אובייקטים נפרדים של ElevationResult.

ב-ElevationService יש שני סוגים של בקשות:

  • בקשות למיקומים נפרדים ונפרדים בשיטה getElevationForLocations(), שמועברת דרך רשימה של מיקום אחד או יותר באמצעות אובייקט LocationElevationRequest.
  • בקשות להעלאה של מספר נקודות מחוברות לאורך נתיב באמצעות השיטה getElevationAlongPath(), שעוברות דרך סדרה מסודרת של קודקודים בתוך אובייקט PathElevationRequest. כשמבקשים גבהים לאורך נתיבים, צריך גם להעביר פרמטר שמציין את מספר הדגימות שרוצים להתקדם במסלול הזה.

כל אחת מהשיטות האלה צריכה גם לעבור שיטת callback כדי לטפל באובייקטים ElevationResult ו-ElevationStatus שמוחזרים.

בקשות גובה מיקום

ליטר אובייקט LocationElevationRequest מכיל את השדה הבא:

{
  locations[]: LatLng
}

locations (חובה) מגדיר את המיקומים על כדור הארץ שמהם יש להחזיר נתוני גובה. הפרמטר הזה מקבל מערך של LatLng שנ'.

אפשר להעביר כל מספר של קואורדינטות במערך, כל עוד לא חרגתם ממכסות השירות. חשוב לזכור שכשמעבירים מספר קואורדינטות, הדיוק של הנתונים המוחזרים עשוי להיות ברזולוציה נמוכה יותר מזו שמבקשים נתונים עבור קואורדינטות בודדות.

דגימות של בקשות להעלאת נתיב

ליטרל אובייקט PathElevationRequest מכיל את השדות הבאים:

{
  path[]: LatLng,
  samples: Number
}

השדות הבאים מוסברים:

  • path (חובה) מגדיר נתיב בכדור הארץ שעבורו יש להחזיר נתוני גובה. הפרמטר path מגדיר קבוצה של 2 צמדים של הסדר {קו רוחב, קו אורך} או יותר, באמצעות מערך של שני אובייקטים או יותר של LatLng.
  • השדה samples (חובה) מציין את מספר הנקודות לדוגמה לאורך נתיב ההחזרה של נתוני הגובה. הפרמטר samples מחלק את path הנתון לקבוצה מסודרת של נקודות מקבילות לאורך הנתיב.

בדומה לבקשות שקשורות למיקום, הפרמטר path מציין קבוצה של ערכים של קווי אורך ורוחב. עם זאת, בניגוד לבקשת מיקום, ה-path מציין קבוצה מסודרת של קודקודים. במקום להחזיר נתוני גובה בקודקודים, בקשות הנתיב נדגמות באורך הנתיב, כאשר כל דגימה שווה זו לזו (כולל נקודות הקצה).

תגובות גובה

לכל בקשה תקינה, שירות הגבהים יחזיר ל-callback המוגדר קבוצה של אובייקטים מסוג ElevationResult עם אובייקט ElevationStatus.

סטטוסים של גובה

כל בקשת העלאה מחזירה את הקוד ElevationStatus בתוך פונקציית הקריאה החוזרת. הקוד status הזה יכיל אחד מהערכים הבאים:

  • OK שמציין שהבקשה לשירות בוצעה בהצלחה
  • INVALID_REQUEST שמציין שבקשת השירות הייתה שגויה
  • OVER_QUERY_LIMIT שמציין כי מגיש הבקשה חרג מהמכסה
  • REQUEST_DENIED שמציין שהשירות לא השלים את הבקשה, ככל הנראה מפני בפרמטר לא חוקי
  • UNKNOWN_ERROR לציון שגיאה לא ידועה

עליך לבדוק שהקריאה החוזרת (callback) שלך הושלמה בהצלחה על ידי בדיקת קוד הסטטוס של OK.

תוצאות גובה

כשהפעולה בוצעה בהצלחה, הארגומנט results של פונקציית הקריאה החוזרת יכיל קבוצה של אובייקטים של ElevationResult. האובייקטים האלה מכילים את הרכיבים הבאים:

  • רכיב location (שמכיל LatLng אובייקטים) של המיקום שעבורו מחושבים נתוני הגובה. לתשומת ליבך: בבקשות לנתיבים, קבוצת הרכיבים של location תכלול את הנקודות שנדגמו לאורך הנתיב.
  • רכיב elevation שמציין את הגובה של המיקום במטרים.
  • ערך resolution, שמציין את המרחק המקסימלי בין נקודות הנתונים שבהן בוצעה אינטרפולציה לגבי הגובה במטרים. הנכס הזה יהיה חסר אם הרזולוציה לא ידועה. הערה: נתוני הגובה הופכים גסים יותר (ערכים גדולים יותר של resolution) כשמעבירים כמה נקודות. כדי לקבל את ערך הגובה המדויק ביותר לנקודה מסוימת, יש לשלוח שאילתה בנפרד.

דוגמאות גובה

הקוד הבא מתרגם קליק במפה לבקשת גובה באמצעות אובייקט 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 },
    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
דוגמה

לדגימה

בדוגמה הבאה נבנית קו מרובה נקודות בהתאם לקבוצת קואורדינטות והצגת נתוני הגובה לאורך המסלול באמצעות Google Vision API. (צריך לטעון את ה-API באמצעות ה-Google Common Loader). בקשת גובה נוצרת באמצעות 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 },
    { 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;
index.js
דוגמה

לדגימה