בקשות הגבהה ותגובות

בקשות להעלאת הרמה

בקשות ל-Elevation API נוצרות כמחרוזת של כתובת URL. ה-API מחזיר נתוני גובה של מיקומים בכדור הארץ. אפשר לציין נתוני מיקום באחת משתי דרכים:

  • כקבוצה של locations אחד או יותר.
  • כסדרה של נקודות מחוברות לאורך path.

בשתי הגישות האלה משתמשים בקואורדינטות של קווי אורך ורוחב כדי לזהות את המיקומים או את קודקודי המסלול. במסמך הזה מתואר הפורמט הנדרש של כתובות ה-URL של Elevation API והפרמטרים הזמינים.

‫Elevation API מחזיר נתונים לשאילתות של נקודה אחת ברמת הדיוק הגבוהה ביותר שאפשר. שאילתות באצווה שכוללות כמה מיקומים עשויות להחזיר נתונים פחות מדויקים, במיוחד אם המיקומים מרוחקים זה מזה, כי מתבצעת החלקה מסוימת של הנתונים.

בקשת Elevation API נראית כך:

https://maps.googleapis.com/maps/api/elevation/outputFormat?parameters

כאשר outputFormat יכול להיות אחד מהערכים הבאים:

  • ‫json (מומלץ), מציין פלט ב-JavaScript Object Notation ‏ (JSON); או
  • xml, מציין פלט ב-XML, עטוף בצומת <ElevationResponse>.

הערה: כדי שכתובות URL יהיו תקינות, הן צריכות להיות מקודדות כמו שצריך. בכל שירותי האינטרנט, כתובות URL מוגבלות ל-16,384 תווים. חשוב לזכור את המגבלה הזו כשיוצרים את כתובות ה-URL. שימו לב שבדפדפנים, בשרתי proxy ובשרתים שונים יכולות להיות מגבלות שונות על מספר התווים בכתובות URL.

חובה להשתמש ב-HTTPS לבקשות שמשתמשות במפתח API.

פרמטרים של בקשות

בקשות ל-Elevation API משתמשות בפרמטרים שונים, בהתאם לסוג הבקשה: מיקומים נפרדים או נתיב מסודר. במיקומים נפרדים, בקשות לגובה מחזירות נתונים על המיקומים הספציפיים שהועברו בבקשה. בנתיבים, בקשות לגובה נדגמות לאורך הנתיב הנתון.

כמו בכל כתובות ה-URL, הפרמטרים מופרדים באמצעות התו אמפרסנד (&amp;). רשימת הפרמטרים והערכים האפשריים שלהם מפורטת בהמשך.

כל הבקשות

  • ‫key – (חובה) מפתח ה-API של האפליקציה. המפתח הזה מזהה את האפליקציה שלכם לצורך ניהול המכסות. איך מקבלים מפתח

בקשות תלויות מיקום

  • ‫locations (חובה) מגדיר את המיקומים בכדור הארץ שמהם יוחזרו נתוני הגובה. הפרמטר הזה מקבל מיקום אחד כצמד {קו רוחב, קו אורך} מופרד בפסיקים (למשל, "40.714728,-73.998672") או כמה צמדים של קווי רוחב/אורך שמועברים כמערך או כקו פוליגוני מקודד. יש מגבלה של 512 נקודות לפרמטר הספציפי הזה. מידע נוסף מופיע בקטע ציון מיקומים בהמשך.

בקשות לנתיב שנדגם

  • path (חובה) מגדיר נתיב בכדור הארץ שעבורו יוחזרו נתוני גובה. הפרמטר הזה מגדיר קבוצה של שני זוגות או יותר של {קו רוחב, קו אורך} מסודרים, שמגדירים מסלול לאורך פני כדור הארץ. צריך להשתמש בפרמטר הזה בשילוב עם הפרמטר 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 נקודות או קואורדינטות בפרמטרים locations או 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 נקודות או קואורדינטות בפרמטרים locations או path, מוחזרת התגובה INVALID_REQUEST.

תשובות לגבי גובה

  • מערך של שתי מחרוזות טקסט או יותר של קואורדינטות, שמופרדות באמצעות פסיקים ומופרדות באמצעות התו קו אנכי ('|'): 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

שדה חובה סוג תיאור
חובה Array<ElevationResult> מידע נוסף זמין במאמר ElevationResult.
חובה ElevationStatus מידע נוסף זמין במאמר בנושא ElevationStatus.
אופציונלי מחרוזת

כשהשירות מחזיר קוד סטטוס שונה מ-OK, יכול להיות שיהיה שדה error_message נוסף באובייקט התגובה. השדה הזה מכיל מידע מפורט יותר על הסיבות לקוד הסטטוס שניתן. השדה הזה לא תמיד מוחזר, והתוכן שלו עשוי להשתנות.

ElevationStatus

קודי סטטוס שמוחזרים על ידי השירות.

  • ‫OK, שמציין שבקשת ה-API בוצעה בהצלחה.
  • ‫DATA_NOT_AVAILABLE, שמציין שאין נתונים זמינים למיקומים שהוזנו.
  • ‫INVALID_REQUEST, שמציין שבקשת ה-API הייתה בפורמט שגוי.
  • OVER_DAILY_LIMIT שמציין אחת מהאפשרויות הבאות:
    • מפתח ה-API חסר או לא תקין.
    • החיוב לא הופעל בחשבון שלכם.
    • חרגתם ממכסת השימוש שהגדרתם לעצמכם.
    • אמצעי התשלום שסופק כבר לא תקף (לדוגמה, פג התוקף של כרטיס האשראי).
  • ‫OVER_QUERY_LIMIT, שמציין שהמבקש חרג מהמכסה.
  • ‫REQUEST_DENIED, שמציין שה-API לא השלים את הבקשה.
  • ‫UNKNOWN_ERROR מציין שגיאה לא ידועה.

אם קוד הסטטוס הוא לא OK, יכול להיות שיהיה שדה error_message נוסף באובייקט התגובה של Elevation. השדה הזה מכיל מידע מפורט יותר על הסיבות לקוד הסטטוס שניתן.

התשובה מכילה מערך results עם הרכיבים הבאים:

ElevationResult

שדה חובה סוג תיאור
חובה number

גובה המיקום במטרים.
חובה LatLngLiteral

רכיב מיקום של הנקודה שעבורה מחושבים נתוני הגובה. שימו לב שבבקשות של מסלולים, קבוצת רכיבי המיקום תכיל את הנקודות שנדגמו לאורך המסלול.

מידע נוסף זמין במאמר LatLngLiteral.

אופציונלי number

הערך שמציין את המרחק המקסימלי בין נקודות על הגרף שמהן בוצעה אינטרפולציה של הגובה, במטרים. המאפיין הזה לא יופיע אם הרזולוציה לא ידועה. חשוב לזכור שנתוני הגובה הופכים לפחות מדויקים (ערכי רזולוציה גדולים יותר) כשמעבירים כמה נקודות. כדי לקבל את ערך הגובה המדויק ביותר של נקודה, צריך לשלוח שאילתה לגביה בנפרד.

LatLngLiteral

אובייקט שמתאר מיקום ספציפי עם קו רוחב וקו אורך במעלות עשרוניות.

שדה חובה סוג תיאור
חובה number

קו רוחב במעלות עשרוניות
חובה number

קו אורך במעלות עשרוניות

דוגמאות לשינוי מיקום של אלמנטים

בדוגמה הבאה נשלחת בקשה לקבלת הגובה של דנבר, קולורדו, "העיר בגובה מייל":

כתובת 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>

בדוגמה הבאה מוצגות כמה תשובות (לדנבר, קולורדו ולעמק המוות, קליפורניה).

הבקשה הזו מדגימה שימוש בדגל ה-JSON‏ output:

כתובת 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>