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

طلبات الارتفاع

يتم إنشاء طلبات Elevation API كسلسلة عنوان 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> node.

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

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

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

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

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

جميع الطلبات

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

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

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

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>

يوضح المثال التالي إجابات متعددة (لمدينة دنفر، كولورادو وادي الموت، كاليفورنيا).

يوضح هذا الطلب كيفية استخدام علامة JSON output:

عنوان 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>