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

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

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

כל הבקשות

• ‫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

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

LatLngLiteral

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

דוגמאות לגובה יחסי

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

https://maps.googleapis.com/maps/api/elevation/json
    ?locations=39.7391536%2C-104.9847034
    &key=YOUR_API_KEY
      

curl -L -X GET 'https://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536%2C-104.9847034&key=YOUR_API_KEY'
      

        
{
  "results":
    [
      {
        "elevation": 1608.637939453125,
        "location": { "lat": 39.7391536, "lng": -104.9847034 },
        "resolution": 4.771975994110107,
      },
    ],
  "status": "OK",
}
        
        

        
<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:

https://maps.googleapis.com/maps/api/elevation/json
    ?locations=39.7391536%2C-104.9847034%7C36.455556%2C-116.866667
    &key=YOUR_API_KEY
      

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.

      
{
  "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",
}
      
      

      
<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, כך שהן יכללו את שתי נקודות הקצה ואת נקודת האמצע.

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 -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'
    

      
{
  "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",
}
      
      

      
<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>