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

בקשות להעלאת גובה

בקשות של Upload API נוצרות כמחרוזת של כתובת URL. ה-API מחזיר נתוני גובה של מיקומים בכדור הארץ. אפשר לציין נתוני מיקום באחת משתי דרכים:

  • כקבוצה של locations או יותר.
  • כסדרה של נקודות מחוברות לאורך path.

בכל אחת מהגישות האלה נעשה שימוש בקואורדינטות של קו אורך/רוחב כדי לזהות את המיקומים או את קודקודי הנתיבים. במסמך הזה מתואר הפורמט הנדרש של כתובות URL של גובה המסך ואת הפרמטרים הזמינים.

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

בקשת API ל-liftion מתבצעת בצורה הבאה:

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.

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

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

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

כל הבקשות

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

בקשות מבוססות-מיקום

  • locations (חובה) מגדיר את המיקומים בכדור הארץ שמהם מוחזרים נתוני גובה. הפרמטר הזה מקבל מיקום יחיד כצמד {latitude,longitude} שמופרד בפסיקים (למשל '40.714728,-73.998672') או כמה זוגות של קווי אורך ורוחב שמועברים כמערך או כקו פוליגוני מקודד. לפרמטר הספציפי הזה יש מגבלה של 512 נקודות. למידע נוסף, ראו ציון מיקומים בהמשך.

דגימות נתיב בקשות

  • path (חובה) מגדיר נתיב בכדור הארץ שעבורו מוחזרים נתוני גובה. הפרמטר הזה מגדיר קבוצה של שני זוגות או יותר לפי קו רוחב של {latitude, Latitude}, שמגדירים נתיב על פני השטח של כדור הארץ. חייבים להשתמש בפרמטר הזה בשילוב עם הפרמטר samples שמתואר בהמשך. יש מגבלה של 512 נקודות לפרמטר הספציפי הזה. מידע נוסף מופיע בקטע ציון נתיבים שבהמשך.
  • samples (חובה) מציין את מספר נקודות הדגימה לאורך נתיב שעבורן מוחזרים נתוני גובה. הפרמטר samples מחלק את הערך הנתון path לקבוצה מסודרת של נקודות דומות לאורך הנתיב.

ציון מיקומים

בקשות מבוססות-מיקום מצוינות באמצעות הפרמטר locations, המציינות בקשות להעלאת גובה במיקומים הספציפיים שמועברים כערכי קו רוחב/קו אורך.

הפרמטר locations יכול לכלול את הארגומנטים הבאים:

  • קואורדינטה יחידה: locations=40.714728,-73.998672
  • מערך של קואורדינטות שמופרדות באמצעות קו הקו ('|') : locations=40.714728,-73.998672|-34.397,150.644
  • קבוצת קואורדינטות מקודדות באמצעות Encoded Polyline Algorithm: locations=enc:gfo}EtohhU

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

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

תגובות גובה

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

דוגמאות לגובה מיקום

הדוגמה הבאה מבקשת את הגובה של דנבר, קולורדו, את 'Mile High City' בפורמט 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 מהר וויטני שבקליפורניה ל-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>