طلبات الزيادة والردود

طلبات العلو

يتم إنشاء طلبات واجهة برمجة التطبيقات للارتفاعات كسلسلة عنوان URL. واجهة برمجة التطبيقات تعرض بيانات الارتفاع للمواقع على الأرض. يمكنك تحديد بيانات الموقع بإحدى طريقتين:

  • كمجموعة من locations واحدة أو أكثر.
  • كسلسلة من النقاط المتصلة على طول path.

يستخدم أي من هذين النهجين إحداثيات خطوط الطول والعرض لتحديد المواقع أو رؤوس المسارات. يصف هذا المستند التنسيق المطلوب لعناوين URL لواجهة برمجة تطبيقات الارتفاع والمعلمات المتاحة.

تقوم Elevation API بإرجاع البيانات لطلبات البحث أحادية النقطة بأعلى دقة ممكنة. قد تعرض طلبات البحث المجمّعة التي تتضمن مواقع متعددة بيانات بدقة أقل، خصوصًا إذا انتشرت المواقع بشكل منفصل، حيث يحدث بعض تجانس البيانات.

يتخذ طلب Elevation API الشكل التالي:

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

حيث قد تكون السمة outputFormat إحدى القيمتَين التاليتَين:

  • json (مقترَح)، يشير إلى الإخراج في JavaScript Object Notation (JSON).
  • وتشير القيمة xml إلى الإخراج بتنسيق XML، والتي تكون مُغلَّفة في عقدة <ElevationResponse>.

ملاحظة: يجب أن تكون عناوين URL مشفَّرة بشكل صحيح لتكون صالحة وتقتصر على 16384 حرفًا في جميع خدمات الويب. ويجب الانتباه إلى هذا الحد عند إنشاء عناوين URL، كما قد يكون لكلٍ من المتصفحات والخوادم الوكيلة والخوادم المختلفة حدود مختلفة لأحرف عناوين URL.

يجب استخدام HTTPS للطلبات التي تستخدم مفتاح واجهة برمجة التطبيقات.

معلَمات الطلب

تستخدم الطلبات إلى Elevation API معلَمات مختلفة بناءً على ما إذا كان الطلب يتعلّق بمواقع منفصلة أو لمسار مُرتب. بالنسبة إلى المواقع المنفصلة، تعرض طلبات الارتفاع بيانات عن المواقع المحددة التي تم تمريرها في الطلب؛ أما بالنسبة إلى المسارات، فيتم أخذ عينات من طلبات الارتفاع على طول المسار المحدد.

وكما هو الحال في جميع عناوين URL، يتم فصل المعلمات باستخدام حرف العطف (&amp;). يُشار إلى قائمة المعلمات وقيمها المحتملة أدناه.

جميع الطلبات

  • key — (مطلوب) مفتاح واجهة برمجة التطبيقات لتطبيقك. يحدِّد هذا المفتاح تطبيقك لأغراض إدارة الحصة. تعرَّف على كيفية الحصول على مفتاح.

طلبات تحديد الموضع

  • تحدد السمة locations (مطلوبة) المواقع الجغرافية على الأرض التي يتم عرض بيانات الارتفاع منها. تأخذ هذه المعلمة إما موقعًا واحدًا كزوج {عرض,خط طول} مفصول بفواصل (على سبيل المثال "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
  • مجموعة من الإحداثيات المرمّزة باستخدام خوارزمية الخط المتعدد المشفر: 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 نقطة أو إحداثيات في مَعلمة "المواقع الجغرافية" أو "المسار"، يتم عرض الاستجابة 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>