סקירה כללית
שירות הגבהה מספק נתוני גובה עבור מיקומים על פני כדור הארץ, כולל מיקומי עומק בקרקעית האוקיינוס (שמחזירים ערכים שליליים). במקרים שבהם אין ל-Google מדידות מדויקות של גובה במיקום המדויק שביקשת, השירות יבצע אינטרפולציה ויחזיר ערך ממוצע באמצעות ארבעת המיקומים הקרובים ביותר.
האובייקט ElevationService
מספק ממשק פשוט לשליחת שאילתות לגבי מיקומים בכדור הארץ לצורך נתוני גובה. בנוסף, אפשר לבקש נתוני גובה שנדגמו לאורך
נתיבים, וכך לחשב את השינויים המתאימים בגובה. האובייקט ElevationService
מתקשר עם שירות הגובה של ממשקי API של מפות Google, שמקבל בקשות גובה ומחזיר נתוני גובה.
באמצעות שירות הרמה, ניתן לפתח אפליקציות להליכה ולרכיבה על אופניים, אפליקציות מיקום לנייד או אפליקציות סקר ברזולוציה נמוכה.
איך מתחילים
לפני השימוש בשירות Elevation API ב-Maps JavaScript API, יש לוודא ש-Elevation API מופעל במסוף Google Cloud באותו פרויקט שהגדרת ב-Maps JavaScript API.
כדי להציג את רשימת ממשקי ה-API המופעלים:
- נכנסים אל Google Cloud Console.
- לוחצים על הלחצן Select a project, בוחרים את הפרויקט שהגדרתם ב-API של JavaScript JavaScript ולוחצים על Open.
- ברשימת ממשקי ה-API במרכז הבקרה, מחפשים את Elevation API.
- אם ה-API מופיע ברשימה, סימן שהכול מוכן. אם ה-API לא מופיע ברשימה,
מפעילים אותו:
- בחלק העליון של הדף בוחרים באפשרות ENABLE API כדי להציג את הכרטיסייה Library. אפשר גם לבחור בתפריט הימני את האפשרות ספרייה.
- מחפשים את Elevation API ובוחרים אותו מרשימת התוצאות.
- לוחצים על הפעלה. בסיום התהליך, 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;
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;
לדגום
בדוגמה הבאה נבנית קו ניוד נתון באמצעות קבוצת קואורדינטות
והצגת נתוני הגובה לאורך הנתיב הזה באמצעות
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;
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;