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

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

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

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

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

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

חובה להשתמש ב-HTTPS לבקשות שמשתמשות במפתח API.

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

הבקשות ל-liftion 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

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

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

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

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