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

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

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

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

עדיין אפשר ליצור כתובת URL תקינה, גם אם מעבירים עד 512 קואורדינטות במערך או בקו פוליגוני מקודד. שימו לב: כשמעבירים כמה קואורדינטות, יכול להיות שהדיוק של הנתונים שיוחזרו יהיה ברזולוציה נמוכה יותר מאשר כשמבקשים נתונים של קואורדינטה אחת. אם חורגים מ-512 נקודות או קואורדינטות בפרמטרים locations או path, מוחזרת תגובה INVALID_REQUEST.

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

לכל בקשה תקינה, שירות מדידת הגובה מעל פני הים יחזיר תגובה של מדידת הגובה מעל פני הים בפורמט שצוין בכתובת ה-URL של הבקשה.

ElevationResponse

FieldRequiredTypeDescription
required Array<ElevationResult> See ElevationResult for more information.
requiredElevationStatus See ElevationStatus for more information.
optionalstring

When the service returns a status code other than OK, there may be an additional error_message field within the response object. This field contains more detailed information about thereasons behind the given status code. This field is not always returned, and its content is subject to change.

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

FieldRequiredTypeDescription
requirednumber

The elevation of the location in meters.

requiredLatLngLiteral

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.

optionalnumber

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.

FieldRequiredTypeDescription
requirednumber

Latitude in decimal degrees

requirednumber

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>