בקשות להעלאת גובה
בקשות של Upload API נוצרות כמחרוזת של כתובת URL. ממשק API מחזירה נתוני גובה עבור מיקומים בכדור הארץ. אתם מציינים נתוני מיקום באחת משתי הדרכים הבאות:
- כקבוצה של
locations
או יותר. - כסדרה של נקודות מחוברות לאורך
path
.
בכל אחת מהגישות האלה נעשה שימוש בקואורדינטות של קו אורך/רוחב כדי לזהות מיקומים או קודקודים בנתיב. במסמך הזה מתואר הפורמט הנדרש כתובות URL של liftion API והפרמטרים הזמינים.
Uploadation API מחזיר נתונים עבור שאילתות שעולות על נקודה אחת ברמת הדיוק הגבוהה ביותר. שאילתות אצווה שכוללות מספר מיקומים עלול להחזיר נתונים ברמת דיוק נמוכה יותר, במיוחד אם המיקומים מחולקים בנפרד, כי החלקה על הנתונים מתבצעת.
בקשת API ל-liftion מתבצעת בצורה הבאה:
https://maps.googleapis.com/maps/api/elevation/outputFormat?parameters
כאשר outputFormat
יכול להיות אחד מהערכים הבאים:
json
(מומלץ), מציין פלט ב: JavaScript Object Notation (JSON); אוxml
, מציין פלט ב-XML, מוקף בתוך צומת<ElevationResponse>
.
הערה: כתובות ה-URL חייבות להיות קידוד נכון להיות חוקיים ומוגבלים ל-16384 תווים עבור כל שירותי האינטרנט. חשוב לשים לב למגבלה הזו כשיוצרים את כתובות ה-URL. שימו לב שבדפדפנים שונים, שרתי proxy ושרתי proxy עשויים להיות בעלי מגבלות תווים שונות בכתובות URL.
נדרש HTTPS בבקשות שמשתמשות במפתח API.
פרמטרים של בקשה
הבקשות ל-Height API מסתמכות על פרמטרים שונים בהתאם האם הבקשה היא למיקומים נפרדים או עבור של הנתיב. למיקומים נפרדים, בקשות להחזרת גובה נתונים לגבי המיקומים הספציפיים שהועברו בבקשה. לנתיבים, במקום זאת, בקשות להעלאת נתונים נדגמים לאורך הנתיב הנתון.
כפי הנהוג בכל כתובות ה-URL, הפרמטרים מופרדים זה מזה
באמצעות תו האמפרסנד (&
). רשימת הפרמטרים
והערכים האפשריים שלהם מסומנים למטה.
כל הבקשות
key
– (חובה) הבקשה שלך מפתח API. המפתח הזה מזהה את האפליקציה שלכם למטרות ניהול מכסות. איך מקבלים מפתח
בקשות מבוססות-מיקום
locations
(חובה) מגדיר את המיקומים כדור הארץ שממנו יש להחזיר נתוני גובה. הפרמטר הזה לוקח מיקום יחיד, בצמד {latitude,longitude} מופרד בפסיקים (למשל: 40.714728,-73.998672) או כמה צמדים של קווי אורך ורוחב מועברות כמערך או כקו פוליגוני מקודד. יש מגבלה של 512 נקודות. לפרמטר הספציפי הזה. לקבלת מידע נוסף, ראה ציון מיקומים למטה.
דגימות נתיב בקשות
path
(חובה) מגדיר נתיב בכדור הארץ עבור שמחזירים נתוני גובה. הפרמטר הזה מגדיר קבוצה של זוגות סדורים יותר של {latitude,longitude} שמגדירים נתיב לאורך פני השטח של כדור הארץ. צריך להשתמש בפרמטר הזה בשילוב עםsamples
שמתואר בהמשך. קיימת מגבלה של 512 נקודות לפריט הזה פרמטר ספציפי. לקבלת מידע נוסף, ראו ציון נתיבים בהמשך.samples
(חובה) מציין את מספר המדגם לאורך נתיב שיחזירו נתוני גובה. הפרמטרsamples
מחלק את הערך הנתון שלpath
לקבוצה מסודרת של נקודות במרחק שווה לאורך הנתיב.
ציון מיקומים
בקשות מבוססות-מיקום מסומנות באמצעות
הפרמטר locations
, שמציין בקשות להעלאת גובה
לגבי המיקומים הספציפיים שמועברים
קווי אורך ורוחב.
הפרמטר locations
יכול לקחת את הערכים הבאים
ארגומנטים:
- קואורדינטה יחידה:
locations=40.714728,-73.998672
- מערך של קואורדינטות מופרדות באמצעות קו אנכי ('
|
') תו:locations=40.714728,-73.998672|-34.397,150.644
- קבוצה של קואורדינטות מקודדות באמצעות הפונקציה
מקודד
אלגוריתם קו פוליגוני:
locations=enc:gfo}EtohhU
מחרוזות קואורדינטות של קווי אורך ורוחב מוגדרות באמצעות ספרות
במחרוזת טקסט שמופרדת בפסיקים. לדוגמה, "40.714728,-73.998672"
הוא ערך חוקי של locations
. קו רוחב וגם
ערכי קו האורך חייבים להתאים למיקום חוקי
על פני כדור הארץ. קווי רוחב יכולים לקבל כל ערך בין
-90
ו-90
בזמן שערכי קו האורך יכולים להימשך
כל ערך בין -180
ל-180
. אם מציינים
ערך לא חוקי של קו רוחב או קו אורך, הבקשה שלך תידחה
כבקשה גרועה.
ניתן להעביר עד 512 קואורדינטות בתוך מערך או מקודד
קו פוליגוני, תוך יצירה של כתובת URL חוקית.
שימו לב שבעת העברת קואורדינטות מרובות, הדיוק של הנתונים שמוחזרים
עשויים להיות ברזולוציה נמוכה יותר מאשר כשמבקשים נתונים לקואורדינטה יחידה.
חריגה מ-512 נקודות או קואורדינטות ב'מיקומים' או 'path' הפונקציה מחזירה
תגובה אחת (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 נקודות או קואורדינטות
ב'מיקומים' או '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 |
דוגמאות לגובה מיקום
הדוגמה הבאה מבקשת את הגובה של דנבר, קולורדו, "העיר הגבוהה של מיילים" בפורמט 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
מהר וויטני, קליפורניה אל באדווטר, קליפורניה,
הנקודות הנמוכות ביותר ביבשת ארצות הברית. אנחנו מבקשים שלוש
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>