בקשות להעלאת גובה
בקשות של Upload API נוצרות כמחרוזת של כתובת URL. ה-API מחזיר נתוני גובה של מיקומים בכדור הארץ. אפשר לציין נתוני מיקום באחת משתי דרכים:
- כקבוצה של
locations
או יותר. - כסדרה של נקודות מחוברות לאורך
path
.
בכל אחת מהגישות האלה נעשה שימוש בקואורדינטות של קו אורך/רוחב כדי לזהות את המיקומים או את קודקודי הנתיבים. במסמך הזה מתואר הפורמט הנדרש של כתובות URL של גובה המסך ואת הפרמטרים הזמינים.
ה-level API מחזיר נתונים מהשאילתות עם נקודה אחת ברמת הדיוק הגבוהה ביותר האפשרית. שאילתות אצווה שכוללות מספר מיקומים עלולות להחזיר נתונים ברמת דיוק נמוכה יותר, במיוחד אם המיקומים מפוזרים על פני השטח, כי מתבצעת החלקה של הנתונים.
בקשת API ל-liftion מתבצעת בצורה הבאה:
https://maps.googleapis.com/maps/api/elevation/outputFormat?parameters
כאשר outputFormat
יכול להיות אחד מהערכים הבאים:
json
(מומלץ), מציין פלט ב-JavaScript Object Notation (JSON); אוxml
, מציין פלט ב-XML שמוקף בצומת<ElevationResponse>
.
הערה: כתובות ה-URL צריכות להיות בקידוד תקין כדי שיהיו חוקיות ומוגבלות ל-16,384 תווים בכל שירותי האינטרנט. חשוב לשים לב למגבלה הזו כשיוצרים את כתובות ה-URL. שימו לב שלדפדפנים, שרתי proxy שונים ושרתים שונים עשויות להיות גם מגבלות תווים שונות לכתובות URL.
נדרש HTTPS בבקשות שמשתמשות במפתח API.
פרמטרים של בקשה
בבקשות ל-level API יש פרמטרים שונים בהתאם למה שהבקשה היא למיקומים נפרדים או לנתיב סדור. במיקומים נפרדים, בקשות לנתוני גובה מוחזרות לגבי המיקומים הספציפיים שמועברים בבקשה. בקשות לגבי נתיבים נדגמים לאורך הנתיב הנתון.
כפי שנהוג בכל כתובות ה-URL, הפרמטרים מופרדים באמצעות תו האמפרסנד (&
). רשימת הפרמטרים והערכים האפשריים שלהם מפורטים למטה.
כל הבקשות
key
– (חובה) מפתח ה-API של האפליקציה. המפתח הזה מזהה את האפליקציה שלכם למטרות ניהול מכסות. איך מקבלים מפתח
בקשות מבוססות-מיקום
locations
(חובה) מגדיר את המיקומים בכדור הארץ שמהם מוחזרים נתוני גובה. הפרמטר הזה מקבל מיקום יחיד כצמד {latitude,longitude} שמופרד בפסיקים (למשל '40.714728,-73.998672') או כמה זוגות של קווי אורך ורוחב שמועברים כמערך או כקו פוליגוני מקודד. לפרמטר הספציפי הזה יש מגבלה של 512 נקודות. למידע נוסף, ראו ציון מיקומים בהמשך.
דגימות נתיב בקשות
path
(חובה) מגדיר נתיב בכדור הארץ שעבורו מוחזרים נתוני גובה. הפרמטר הזה מגדיר קבוצה של שני זוגות או יותר לפי קו רוחב של {latitude, Latitude}, שמגדירים נתיב על פני השטח של כדור הארץ. חייבים להשתמש בפרמטר הזה בשילוב עם הפרמטרsamples
שמתואר בהמשך. יש מגבלה של 512 נקודות לפרמטר הספציפי הזה. מידע נוסף מופיע בקטע ציון נתיבים שבהמשך.samples
(חובה) מציין את מספר נקודות הדגימה לאורך נתיב שעבורן מוחזרים נתוני גובה. הפרמטרsamples
מחלק את הערך הנתוןpath
לקבוצה מסודרת של נקודות דומות לאורך הנתיב.
ציון מיקומים
בקשות מבוססות-מיקום מצוינות באמצעות הפרמטר locations
, המציינות בקשות להעלאת גובה במיקומים הספציפיים שמועברים כערכי קו רוחב/קו אורך.
הפרמטר locations
יכול לכלול את הארגומנטים הבאים:
- קואורדינטה יחידה:
locations=40.714728,-73.998672
- מערך של קואורדינטות שמופרדות באמצעות קו הקו ('
|
') :locations=40.714728,-73.998672|-34.397,150.644
- קבוצת קואורדינטות מקודדות באמצעות Encoded
Polyline Algorithm:
locations=enc:gfo}EtohhU
מחרוזות קואורדינטות של קווי אורך ורוחב מוגדרות באמצעות ספרות במחרוזת טקסט שמופרדת בפסיקים. לדוגמה, 40.714728,-73.998672 הוא ערך locations
חוקי. הערכים של קו הרוחב וקו האורך צריכים להתאים למיקום תקין על פני כדור הארץ. קווי האורך יכולים לקבל כל ערך בין -90
ל-90
, בעוד שערכי קו האורך יכולים לקבל כל ערך בין -180
ל-180
. אם תציינו ערך לא תקין של קו רוחב או קו אורך, הבקשה תידחה כבקשה לא תקינה.
אפשר להעביר עד 512 קואורדינטות בתוך מערך או קו פוליגוני מקודד, ועדיין ליצור כתובת URL תקינה.
שימו לב שכשמעבירים מספר קואורדינטות, הדיוק של הנתונים שמוחזרים עשוי להיות ברזולוציה נמוכה יותר מאשר כשמבקשים נתונים לקואורדינטה יחידה.
חריגה מ-512 נקודות או קואורדינטות בפרמטרים 'מיקומים' או 'נתיב' תחזיר את התשובה INVALID_REQUEST
.
ציון נתיבים
בקשות לנתיב שנדגמו מצוינות באמצעות שימוש בפרמטרים path
ו-samples
, דבר שמציין בקשה לנתוני גובה לאורך נתיב במרווחי זמן מוגדרים. בדומה לבקשות מבוססות-מיקום שמשתמשות בפרמטר locations
, הפרמטר path
מציין קבוצה של ערכים של קו רוחב וקו אורך. אבל בניגוד לבקשת מיקום, path
מציין קבוצה ממוינת של קודקודים. במקום להחזיר נתוני גובה רק בקודקודים, בקשות הנתיבים נדגמות לאורך הנתיב על סמך מספר ה-samples
שצוין (כולל נקודות הקצה).
הפרמטר path
יכול לכלול כל אחד מהארגומנטים הבאים:
- מערך של שתי מחרוזות טקסט של קואורדינטות או יותר שמופרדות בפסיקים, שמופרדות באמצעות הקו הניצב ('
|
') :path=40.714728,-73.998672|-34.397,150.644
- הקואורדינטות המקודדות באמצעות
האלגוריתם המקודד
המקודד:
path=enc:gfo}EtohhUxD@bAxJmGF
מחרוזות קואורדינטות של קווי אורך ורוחב מוגדרות באמצעות ספרות במחרוזת טקסט שמופרדת בפסיקים. לדוגמה, "40.714728,-73.998672|-34.397, 150.644" הוא ערך path
חוקי. הערכים של קו הרוחב וקו האורך חייבים להתאים למיקום תקין על פני כדור הארץ. קווי האורך יכולים לקבל כל ערך בין -90
ל-90
, בעוד שערכי קו האורך יכולים לקבל כל ערך בין -180
ל-180
. אם תציינו ערך לא תקין של קו רוחב או קו אורך, הבקשה תידחה כבקשה לא תקינה.
אפשר להעביר עד 512 קואורדינטות בתוך מערך או קו פוליגוני מקודד, ועדיין ליצור כתובת URL תקינה. שימו לב שכשמעבירים מספר קואורדינטות, הדיוק של הנתונים שמוחזרים עשוי להיות ברזולוציה נמוכה יותר מאשר כשמבקשים נתונים לקואורדינטה יחידה. חריגה מ-512 נקודות או קואורדינטות
בפרמטרים 'locations' או 'path' תחזיר את התשובה INVALID_REQUEST
.
תגובות גובה
לכל בקשה תקינה, שירות גובה מחזיר תגובת גובה בפורמט שמצוין בכתובת ה-URL של הבקשה.
ElevationResponse
Field | Required | Type | Description |
---|---|---|---|
| required | Array<ElevationResult> | See ElevationResult for more information. |
| required | ElevationStatus | See ElevationStatus for more information. |
| optional | string |
When the service returns a status code other than |
ElevationStatus
Status codes returned by service.
OK
indicating the API request was successful.DATA_NOT_AVAILABLE
indicating that there's no available data for the input locations.INVALID_REQUEST
indicating the API request was malformed.OVER_DAILY_LIMIT
indicating any of the following:- The API key is missing or invalid.
- Billing has not been enabled on your account.
- A self-imposed usage cap has been exceeded.
- The provided method of payment is no longer valid (for example, a credit card has expired).
OVER_QUERY_LIMIT
indicating the requestor has exceeded quota.REQUEST_DENIED
indicating the API did not complete the request.UNKNOWN_ERROR
indicating an unknown error.
אם קוד הסטטוס הוא לא OK
, יכול להיות שיופיע שדה error_message
נוסף בתוך האובייקט של תגובת הגבהה. בשדה הזה יש מידע מפורט יותר על הסיבות לקוד הסטטוס הנתון.
התגובה מכילה מערך results
עם הרכיבים הבאים:
ElevationResult
Field | Required | Type | Description |
---|---|---|---|
| required | number | The elevation of the location in meters. |
| required | LatLngLiteral | A location element of the position for which elevation data is being computed. Note that for path requests, the set of location elements will contain the sampled points along the path. See LatLngLiteral for more information. |
| optional | number | The value indicating the maximum distance between data points from which the elevation was interpolated, in meters. This property will be missing if the resolution is not known. Note that elevation data becomes more coarse (larger resolution values) when multiple points are passed. To obtain the most accurate elevation value for a point, it should be queried independently. |
האובייקט location
מכיל את הרכיבים הבאים:
LatLngLiteral
An object describing a specific location with Latitude and Longitude in decimal degrees.
Field | Required | Type | Description |
---|---|---|---|
| required | number | Latitude in decimal degrees |
| required | number | Longitude in decimal degrees |
דוגמאות לגובה מיקום
הדוגמה הבאה מבקשת את הגובה של דנבר, קולורדו, את 'Mile High City' בפורמט JSON:
כתובת URL
https://maps.googleapis.com/maps/api/elevation/json ?locations=39.7391536%2C-104.9847034 &key=YOUR_API_KEY
cURL
curl -L -X GET 'https://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536%2C-104.9847034&key=YOUR_API_KEY'
JSON
{ "results": [ { "elevation": 1608.637939453125, "location": { "lat": 39.7391536, "lng": -104.9847034 }, "resolution": 4.771975994110107, }, ], "status": "OK", }
XML
<ElevationResponse> <status>OK</status> <result> <location> <lat>39.7391536</lat> <lng>-104.9847034</lng> </location> <elevation>1608.6379395</elevation> <resolution>4.7719760</resolution> </result> </ElevationResponse>
בדוגמה הבאה מוצגות מספר תשובות (לדנוור, לקולורדו ולמוות עמק המוות, קליפורניה).
הבקשה הזו מדגימה באמצעות הדגל output
של JSON:
כתובת URL
https://maps.googleapis.com/maps/api/elevation/json ?locations=39.7391536%2C-104.9847034%7C36.455556%2C-116.866667 &key=YOUR_API_KEY
cURL
curl -L -X GET 'https://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536%2C-104.9847034%7C36.455556%2C-116.866667&key=YOUR_API_KEY'
הבקשה הזו מדגימה באמצעות הדגל output
של XML:
https://maps.googleapis.com/maps/api/elevation/xml?locations=39.7391536,-104.9847034|36.455556,-116.866667&key=YOUR_API_KEY
בכרטיסיות שלמטה ניתן לראות תגובות JSON ו-XML לדוגמה.
JSON
{ "results": [ { "elevation": 1608.637939453125, "location": { "lat": 39.7391536, "lng": -104.9847034 }, "resolution": 4.771975994110107, }, { "elevation": -52.79492568969727, "location": { "lat": 36.455556, "lng": -116.866667 }, "resolution": 19.08790397644043, }, ], "status": "OK", }
XML
<ElevationResponse> <status>OK</status> <result> <location> <lat>39.7391536</lat> <lng>-104.9847034</lng> </location> <elevation>1608.6379395</elevation> <resolution>4.7719760</resolution> </result> <result> <location> <lat>36.4555560</lat> <lng>-116.8666670</lng> </location> <elevation>-52.7949257</elevation> <resolution>19.0879040</resolution> </result> </ElevationResponse>
הדוגמאות הבאות מבקשות נתוני גובה לאורך קו ישר path
מהר וויטני שבקליפורניה ל-Badwater, CA – הנקודות הגבוהות והנמוכות ביותר בארצות הברית. אנחנו מבקשים שלוש samples
, כך שהן יכללו את שתי נקודות הקצה ואת נקודת היעד.
כתובת URL
https://maps.googleapis.com/maps/api/elevation/json ?path=36.578581%2C-118.291994%7C36.23998%2C-116.83171 &samples=3 &key=YOUR_API_KEY
cURL
curl -L -X GET 'https://maps.googleapis.com/maps/api/elevation/json?path=36.578581%2C-118.291994%7C36.23998%2C-116.83171&samples=3&key=YOUR_API_KEY'
JSON
{ "results": [ { "elevation": 4411.94189453125, "location": { "lat": 36.578581, "lng": -118.291994 }, "resolution": 19.08790397644043, }, { "elevation": 1372.8359375, "location": { "lat": 36.41150289067028, "lng": -117.5602607523847 }, "resolution": 9.543951988220215, }, { "elevation": -84.51690673828125, "location": { "lat": 36.23998, "lng": -116.83171 }, "resolution": 9.543951988220215, }, ], "status": "OK", }
XML
<ElevationResponse> <status>OK</status> <result> <location> <lat>36.5785810</lat> <lng>-118.2919940</lng> </location> <elevation>4411.9418945</elevation> <resolution>19.0879040</resolution> </result> <result> <location> <lat>36.4115029</lat> <lng>-117.5602608</lng> </location> <elevation>1372.8359375</elevation> <resolution>9.5439520</resolution> </result> <result> <location> <lat>36.2399800</lat> <lng>-116.8317100</lng> </location> <elevation>-84.5169067</elevation> <resolution>9.5439520</resolution> </result> </ElevationResponse>