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

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

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

מחרוזות של קואורדינטות קו רוחב וקו אורך מוגדרות באמצעות מספרים במחרוזת טקסט מופרדת בפסיקים. לדוגמה, הערך locations החוקי הוא '40.714728,-73.998672'. ערכי קו הרוחב וקו האורך חייבים להתאים למיקום חוקי על פני כדור הארץ. קוי רוחב יכולים לקבל כל ערך בין -90 ל-90, וקווי אורך יכולים לקבל כל ערך בין -180 ל-180. אם מציינים ערך לא חוקי של קו הרוחב או קו האורך, הבקשה תידחה כבקשה לא תקינה.

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

ציון נתיבים

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

הפרמטר path יכול לקבל את אחד מהארגומנטים הבאים:

  • מערך של שתי מחרוזות טקסט או יותר של קואורדינטות מופרדות בפסיקים, שמפרידים אותן באמצעות התו קו אנכי (|): path=40.714728,-73.998672|-34.397,150.644
  • קואורדינטות מקודדות באמצעות אלגוריתם קווים פולינימיים מקודדים: path=enc:gfo}EtohhUxD@bAxJmGF

מחרוזות של קואורדינטות קו רוחב וקו אורך מוגדרות באמצעות מספרים במחרוזת טקסט מופרדת בפסיקים. לדוגמה, הערך path החוקי הוא '40.714728,-73.998672|-34.397, 150.644'. הערכים של קו הרוחב וקו האורך חייבים להתאים למיקום תקף על פני כדור הארץ. קוי רוחב יכולים לקבל כל ערך בין -90 ל-90, וקווי אורך יכולים לקבל כל ערך בין -180 ל-180. אם מציינים ערך לא חוקי של קו הרוחב או קו האורך, הבקשה תידחה כבקשה לא תקינה.

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

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

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

התשובה מכילה מערך 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 מ-Mt. Whitney, CA אל Badwater, CA, הנקודות הגבוהה והנמוכה ביותר בארצות הברית היבשתית. אנחנו מבקשים שלוש 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>