דף זה תורגם על ידי Cloud Translation API.

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

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

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

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

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

ה-Uploadion 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.

פרמטרים של בקשות

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

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

כל הבקשות

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
קבוצת קואורדינטות מקודדות באמצעות Encoded Polyline Algorithm: locations=enc:gfo}EtohhU

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

תגובות גובה

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

ElevationResponse

Field	Required	Type	Description
`results`	required	Array<ElevationResult>	See ElevationResult for more information.
`status`	required	ElevationStatus	See ElevationStatus for more information.
`error_message`	optional	string	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

Field	Required	Type	Description
`elevation`	required	number	The elevation of the location in meters.
`location`	required	LatLngLiteral	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.
`resolution`	optional	number	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.

Field	Required	Type	Description
`lat`	required	number	Latitude in decimal degrees
`lng`	required	number	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>

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

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

פרמטרים של בקשות

כל הבקשות

בקשות תלויות מיקום

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

ציון מיקומים

ציון נתיבים

תגובות גובה

ElevationResponse

`results`

`status`

`error_message`

ElevationStatus

ElevationResult

`elevation`

`location`

`resolution`

LatLngLiteral

`lat`

`lng`

דוגמאות לגובה גיאוגרפי

כתובת URL

cURL

JSON

XML

כתובת URL

cURL

JSON

XML

כתובת URL

cURL

JSON

XML