שירות גבהים

סקירה כללית

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

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

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

תחילת העבודה

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

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

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

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

תמחור

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

מדיניות

השימוש בשירות הגובה חייב להיות בהתאם המדיניות שמתוארת ל-liftion API.

בקשות להעלאת נתונים

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

ElevationService מטפל בשני סוגים של בקשות:

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

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

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

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

{
  locations[]: LatLng
}

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

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

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

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

{
  path[]: LatLng,
  samples: Number
}

הסבר על השדות האלה:

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

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

תגובות גובה

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

סטטוסי גובה

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

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

כדי לוודא שהקריאה החוזרת הצליחה קוד הסטטוס של OK.

תוצאות גובה

לאחר ההצלחה, הארגומנט results של הקריאה החוזרת (callback) הפונקציה תכיל קבוצה של 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;

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;
להצגת דוגמה

כדאי לנסות דוגמה

הדוגמה הבאה יוצרת קו פוליגוני בהינתן קבוצה של קואורדינטות ומציג נתוני גובה לאורך הנתיב באמצעות Google חזותית API. (יש לטעון את ה-API הזה באמצעות 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;

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;
להצגת דוגמה

כדאי לנסות דוגמה