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

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

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

חובה להשתמש ב-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 תקינה. חשוב לזכור שכאשר מעבירים כמה קואורדינטות, רמת הדיוק של הנתונים שמוחזרים עשויה להיות נמוכה יותר מאשר כשמבקשים נתונים לגבי קואורדינטה אחת. אם מספר הנקודות או הקואורדינטות בפרמטרים 'locations' או 'path' חורג מ-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>