סקירה כללית
שירות הגובה מספק נתוני גובה של מיקומים על פני כדור הארץ, כולל מיקומי עומק בקרקעית האוקיינוס (שמחזירים ערכים שליליים). במקרים שבהם ל-Google אין מדידות גובה מדויקות במיקום המדויק שביקשתם, השירות יבצע אינטרפולציה ויחזיר ערך ממוצע באמצעות ארבעת המיקומים הקרובים ביותר.
האובייקט ElevationService מספק ממשק פשוט לשליחת שאילתות לגבי נתוני גובה של מיקומים בכדור הארץ. בנוסף, אתם יכולים לבקש נתוני גובה שנדגמו לאורך מסלולים, כדי לחשב את השינויים בגובה במרחקים שווים לאורך המסלולים. האובייקט ElevationService מתקשר עם שירות הגובה של Google Maps API, שמקבל בקשות לגובה ומחזיר נתוני גובה.
בעזרת שירות הגובה, אתם יכולים לפתח אפליקציות לטיולים רגליים ולרכיבה על אופניים, אפליקציות למיקום בנייד או אפליקציות למדידה ברזולוציה נמוכה.
תחילת העבודה
לפני שמשתמשים בשירות הגובה ב-Maps JavaScript API, צריך לוודא ש-Elevation API מופעל במסוף Google Cloud, באותו פרויקט שהגדרתם ל-Maps JavaScript API.
כדי לראות את רשימת ממשקי ה-API שמופעלים:
- נכנסים ל מסוף Google Cloud.
- לוחצים על הכפתור Select a project, בוחרים את הפרויקט שהגדרתם ל-Maps JavaScript API ולוחצים על Open.
- ברשימת ממשקי ה-API במרכז הבקרה, מחפשים את Elevation API.
- אם ה-API מופיע ברשימה, אתם מוכנים. אם ה-API לא מופיע ברשימה, מפעילים אותו:
- בחלק העליון של הדף, לוחצים על ENABLE API כדי להציג את הכרטיסייה Library. אפשר גם ללחוץ על ספרייה בתפריט הימני.
- מחפשים את Elevation API ובוחרים אותו מרשימת התוצאות.
- לוחצים על הפעלה. בסיום התהליך, Elevation API יופיע ברשימת ממשקי ה-API במרכז הבקרה.
תמחור ומדיניות
תמחור
במאמר שימוש וחיוב של Elevation API מפורט מידע על מדיניות התמחור והשימוש בשירות הגובה של JavaScript.
מדיניות
השימוש בשירות Elevation חייב להיות בהתאם למדיניות שמתוארת לגבי Elevation API.
בקשות להרשאות ניהול
הגישה לשירות הגובה היא אסינכרונית, כי Google Maps API צריך לבצע קריאה לשרת חיצוני. לכן צריך להעביר שיטת קריאה חוזרת (callback) שתתבצע בסיום הבקשה. שיטת הקריאה החוזרת הזו אמורה לעבד את התוצאות. שימו לב ששירות הגובה מחזיר קוד סטטוס (ElevationStatus) ומערך של אובייקטים נפרדים מסוג ElevationResult.
ה-ElevationService מטפל בשני סוגים של בקשות:
- בקשות למיקומים נפרדים וספציפיים באמצעות ה-method
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 מצוינת קבוצה מסודרת של קודקודים. במקום להחזיר נתוני גובה בקודקודים, בקשות למסלול נדגמות לאורך המסלול, כאשר כל דגימה נמצאת במרחק שווה מהאחרות (כולל נקודות הקצה).
תשובות במצב Elevation
לכל בקשה תקינה, שירות הגובה יחזיר לקריאה החוזרת (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
async function init(): Promise<void> { const [{ InfoWindow }, { ElevationService }] = await Promise.all([ google.maps.importLibrary('maps'), google.maps.importLibrary('elevation'), ]); const mapElement = document.querySelector('gmp-map')!; const innerMap = mapElement.innerMap; const elevator = new ElevationService(); const infowindow = new InfoWindow(); infowindow.open(innerMap); // Add a listener for the click event. Display the elevation for the LatLng of // the click inside the infowindow. innerMap.addListener('click', (event: google.maps.MapMouseEvent) => { displayLocationElevation(event.latLng!, elevator, infowindow, innerMap); }); } function displayLocationElevation( location: google.maps.LatLng, elevator: google.maps.ElevationService, infowindow: google.maps.InfoWindow, map: google.maps.Map ) { // Format numeric values to two decimal places const formatter = new Intl.NumberFormat(undefined, { maximumFractionDigits: 2, }); // Initiate the location request elevator .getElevationForLocations({ locations: [location], }) .then(({ results }) => { if (results[0]) { const { elevation, location: resultLocation } = results[0]; infowindow.setPosition(resultLocation); infowindow.setContent( `The elevation at ${String(resultLocation)} <br>is ${formatter.format(elevation)} meters.` ); } else { infowindow.setPosition(location); infowindow.setContent('No results found'); } infowindow.open(map); }) .catch((e: unknown) => { infowindow.setContent( `Elevation service failed due to: ${String(e)}` ); }); } void init();
JavaScript
async function init() { const [{ InfoWindow }, { ElevationService }] = await Promise.all([ google.maps.importLibrary('maps'), google.maps.importLibrary('elevation'), ]); const mapElement = document.querySelector('gmp-map'); const innerMap = mapElement.innerMap; const elevator = new ElevationService(); const infowindow = new InfoWindow(); infowindow.open(innerMap); // Add a listener for the click event. Display the elevation for the LatLng of // the click inside the infowindow. innerMap.addListener('click', (event) => { displayLocationElevation(event.latLng, elevator, infowindow, innerMap); }); } function displayLocationElevation(location, elevator, infowindow, map) { // Format numeric values to two decimal places const formatter = new Intl.NumberFormat(undefined, { maximumFractionDigits: 2, }); // Initiate the location request elevator .getElevationForLocations({ locations: [location], }) .then(({ results }) => { if (results[0]) { const { elevation, location: resultLocation } = results[0]; infowindow.setPosition(resultLocation); infowindow.setContent( `The elevation at ${String(resultLocation)} <br>is ${formatter.format(elevation)} meters.` ); } else { infowindow.setPosition(location); infowindow.setContent('No results found'); } infowindow.open(map); }) .catch((e) => { infowindow.setContent( `Elevation service failed due to: ${String(e)}` ); }); } void init();
בדוגמה הבאה, קו פוליגוני נוצר על סמך קבוצה של קואורדינטות, ונתוני הגובה לאורך המסלול מוצגים באמצעות
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 }, // 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;