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