סקירה כללית
שירות הגובה מספק נתוני גובה למיקומים על פני השטח של כדור הארץ, כולל מיקומי עומק בקרקעית האוקיינוס (שמחזירים ערכים שליליים). במקרים שבהם ל-Google אין מדידות גובה מדויקות במיקום המדויק שביקשת, השירות יבצע אינטרפולציה ויחזיר ערך ממוצע באמצעות ארבעת המיקומים הקרובים ביותר.
לאובייקט ElevationService
יש ממשק פשוט לביצוע שאילתות על מיקומים בכדור הארץ לגבי נתוני גובה. בנוסף, ניתן לבקש נתוני גובה שנדגמו לאורך נתיבים, וכך לחשב את שינויי הגובה השווים במסלולים. האובייקט ElevationService
מתקשר עם שירות הגובה של ה-API של מפות Google, שמקבל בקשות לגבי גובה ומחזיר נתוני גובה.
באמצעות שירות הגובה תוכלו לפתח אפליקציות לטיולים רגליים ולרכיבה על אופניים, אפליקציות למיקום מכשירים ניידים או אפליקציות סקרים ברזולוציה נמוכה.
איך מתחילים
לפני שמשתמשים בשירות הגובה ב- Maps JavaScript API, צריך קודם לוודא ש-Elevation API מופעל במסוף Google Cloud, באותו פרויקט שהגדרתם ל- Maps JavaScript API.
כדי להציג את רשימת ממשקי ה-API המופעלים:
- נכנסים ל מסוף Google Cloud.
- לוחצים על הלחצן Select a project (בחירת פרויקט), בוחרים את הפרויקט שהגדרתם עבור Maps JavaScript API ולוחצים על Open.
- מחפשים את Elevation API ברשימת ממשקי ה-API במרכז הבקרה.
- אם ממשק ה-API מופיע ברשימה, הכול מוכן. אם ממשק ה-API לא מופיע ברשימה,
מפעילים אותו:
- בחלק העליון של הדף, לוחצים על ENABLE API כדי להציג את הכרטיסייה Library. לחלופין, בתפריט הימני לוחצים על ספרייה.
- מחפשים את Elevation API ובוחרים את ה-API מרשימת התוצאות.
- בוחרים באפשרות הפעלה. בסיום התהליך, Elevation API מופיע ברשימת ממשקי ה-API במרכז הבקרה.
תמחור ומדיניות
תמחור
ב-16 ביולי 2018 נכנסה לתוקף תוכנית תמחור ותשלומים לפי תשלום לפי שימוש במפות, ב'מסלולים' וב'מקומות'. בקטע Usage and Billing ל-Elevation API, תוכלו לקרוא מידע נוסף על המגבלות החדשות של התמחור והשימוש בשירות JavaScript.
כללי מדיניות
השימוש בשירות הגובה חייב להיות בהתאם למדיניות שמתוארת ב-Elevation API.
בקשות גובה
הגישה לשירות הגובה היא אסינכרונית, מכיוון ש-Google Maps API צריך לבצע קריאה לשרת חיצוני. לכן צריך להעביר שיטת callback כדי שתתבצע אחרי השלמת הבקשה. שיטת הקריאה החוזרת(callback) הזו אמורה לעבד את התוצאות. שימו לב ששירות הגובה מחזיר קוד סטטוס (ElevationStatus
) ומערך של אובייקטים נפרדים מסוג ElevationResult
.
ElevationService
מטפל בשני סוגים של בקשות:
- בקשות למיקומים נפרדים ונפרדים באמצעות השיטה
getElevationForLocations()
, שמועברת רשימה של מיקום אחד או יותר באמצעות אובייקטLocationElevationRequest
. - בקשות לגבי גובה של סדרה של נקודות מחוברות
לאורך נתיב באמצעות השיטה
getElevationAlongPath()
, שעוברת קבוצה מסודרת של קודקודים בנתיב בתוך אובייקטPathElevationRequest
. כשמבקשים הגבהות לאורך נתיבים, צריך גם להעביר פרמטר שמציין כמה דוגמאות רוצים לקחת לאורך הנתיב.
בכל אחת מהשיטות האלה צריך גם להעביר שיטת callback כדי לטפל באובייקטים ElevationResult
ו-ElevationStatus
שהוחזרו.
בקשות להעלאת מיקום
ליטרל של אובייקט LocationElevationRequest
מכיל את השדה הבא:
{ locations[]: LatLng }
locations
(חובה) מגדיר את המיקומים בכדור הארץ שמהם יש להחזיר נתוני גובה. הפרמטר הזה מקבל מערך של
LatLng
.
אפשר להעביר כמה קואורדינטות בתוך מערך, כל עוד לא חורגים ממכסות השירות. הערה: כשמעבירים כמה קואורדינטות, הדיוק של הנתונים שמוחזרים עשוי להיות ברזולוציה נמוכה יותר מאשר כשמבקשים נתונים לקואורדינטות אחת.
בקשות העלאת גובה בנתיב שנדגמו
ליטרל של אובייקט PathElevationRequest
מכיל את השדות הבאים:
{ path[]: LatLng, samples: Number }
שדות אלה מוסברים בהמשך:
path
(חובה) מגדיר נתיב בכדור הארץ שעבורו ניתן להחזיר נתוני גובה. הפרמטרpath
מגדיר קבוצה של שני צמדים או יותר בסדר {קו רוחב, קו אורך}, באמצעות מערך של שני אובייקטים או יותר מסוגLatLng
.samples
(חובה) מציין את מספר נקודות הדגימה לאורך נתיב שעבורן יחזירו נתוני גובה. הפרמטרsamples
מחלק אתpath
הנתון לקבוצה מסודרת של נקודות שווי ערך לאורך הנתיב.
בדומה לבקשות הנוגעות למיקום, הפרמטר path
מציין קבוצה של ערכים של קווי אורך ורוחב. עם זאת, בשונה מבקשת מיקום,
עם זאת, ב-path
מציינים קבוצה ממוינת של קודקודים. במקום להציג נתוני גובה בקודקודים, בקשות הנתיב נדגמים לאורך הנתיב, כאשר כל דגימה במרחק שווה זו מזו (כולל נקודות הקצה).
תגובות עליות/ירידות
עבור כל בקשה חוקית, שירות הגובה יחזיר אל קבוצת האובייקטים ElevationResult
שהוגדרה קריאה חוזרת (callback) יחד עם אובייקט 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;
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;
ניסוי לדוגמה
בדוגמה הבאה נוצר קו מרובה נקודות (polyline) בהינתן קבוצת קואורדינטות, ומציגים נתוני גובה לאורך הנתיב באמצעות
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;
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;