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

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

בקשות לגובה

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

כל הבקשות

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

בקשות להצגת מודעות לפי מיקום

locations (חובה) מגדיר את המיקומים בכדור הארץ שמהם יש להחזיר נתוני גובה. הפרמטר הזה מקבל מיקום יחיד כצמד {latitude,longitude} מופרד בפסיקים (למשל, '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
קבוצת קואורדינטות מקודדות באמצעות אלגוריתם ה-Polyline המקודד: 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
קואורדינטות מקודדות באמצעות אלגוריתם ה-Polyline המקודד: path=enc:gfo}EtohhUxD@bAxJmGF

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

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

תגובות לצורך עלייה

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

התשובה מכילה מערך 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

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

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

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

בקשות לגובה

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

כל הבקשות

בקשות להצגת מודעות לפי מיקום

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

ציון מיקומים

ציון נתיבים

תגובות לצורך עלייה

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