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

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

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

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

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

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

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

https://maps.googleapis.com/maps/api/elevation/outputFormat?parameters

כאשר outputFormat יכול להיות אחד מהערכים הבאים:

  • json (מומלץ), מציין פלט ב: JavaScript Object Notation (JSON); או
  • xml, מציין פלט ב-XML, מוקף בתוך צומת <ElevationResponse>.

הערה: כתובות ה-URL חייבות להיות קידוד נכון להיות חוקיים ומוגבלים ל-16384 תווים עבור כל שירותי האינטרנט. חשוב לשים לב למגבלה הזו כשיוצרים את כתובות ה-URL. שימו לב שבדפדפנים שונים, שרתי proxy ושרתי proxy עשויים להיות בעלי מגבלות תווים שונות בכתובות URL.

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

תגובות גובה

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