שירות גבהים

סקירה כללית

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

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

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

איך מתחילים

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

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

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

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

תמחור

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

מדיניות

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

בקשות גובה

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

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

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

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

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

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

{
  locations[]: LatLng
}

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

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

דוגמאות לדגימות של נתיב

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

{
  path[]: LatLng,
  samples: Number
}

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

  • path (חובה) מגדיר נתיב בכדור הארץ שעבורו יחזרו נתוני גובה. הפרמטר path מגדיר קבוצה של שני צמדים מסודרים לפי סדר {width,length} או יותר, באמצעות מערך של שני אובייקטים או יותר מסוג 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 Visualization 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
דוגמה

לדגום