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

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

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

  • كمجموعة من 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> node.

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

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

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

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

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

جميع الطلبات

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

الطلبات المتعلّقة بالموقع الجغرافي

  • 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
  • مجموعة من الإحداثيات المشفَّرة باستخدام خوارزمية 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.

استجابات الارتفاع

لكل طلب صالح، ستعرض خدمة 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 ضمن عنصر استجابة Elevation. يحتوي هذا الحقل على معلومات أكثر تفصيلاً عن أسباب ظهور رمز الحالة المحدّد.

يحتوي الردّ على صفيف 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>