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

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

בקשות ל-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 צריכות להיות מקודדות בצורה נכונה כדי להיות תקפות, והן מוגבלות ל-16,384 תווים בכל שירותי האינטרנט. חשוב להיות מודעים למגבלה הזו כשיוצרים כתובות URL. שימו לב שגם בדפדפנים, בשרתי proxy ובשרתים שונים יכולות להיות מגבלות שונות על מספר התווים בכתובות URL.

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

פרמטרים של בקשה

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

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

כל הבקשות

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

בקשות מיקום

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

התשובה מכילה מערך 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>

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

בדוגמה הזו אפשר לראות איך משתמשים בדגל 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>