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

طلبات رفع مستوى الوصول

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

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

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

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

يأخذ طلب بيانات من واجهة برمجة التطبيقات Elevation الشكل التالي:

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

حيث يمكن أن تكون قيمة outputFormat أيًا مما يلي:

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

ملاحظة: يجب أن تكون عناوين URL مُرمَّزة بشكل صحيح لتكون صالحة، ويجب ألا تتجاوز 16,384 حرفًا لجميع خدمات الويب. يُرجى الانتباه إلى هذا الحدّ عند إنشاء عناوين 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.

الردود على طلبات التصعيد

  • مصفوفة من سلسلتَين نصيتَين أو أكثر من الإحداثيات المفصولة بفواصل، ويتم الفصل بينها باستخدام رمز الشرطة الرأسية ('|'): 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.

الردود على طلبات التصعيد

لكل طلب صالح، تعرض خدمة Elevation استجابة Elevation بالتنسيق المحدّد في عنوان URL للطلب.

ElevationResponse

الحقل مطلوب النوع الوصف
مطلوب Array<ElevationResult> يمكنك الاطّلاع على ElevationResult لمزيد من المعلومات.
مطلوب ElevationStatus يمكنك الاطّلاع على ElevationStatus لمزيد من المعلومات.
اختياري سلسلة

عندما تعرض الخدمة رمز حالة غير OK، قد يكون هناك حقل error_message إضافي ضمن عنصر الاستجابة. يحتوي هذا الحقل على معلومات أكثر تفصيلاً عن الأسباب وراء رمز الحالة المحدّد. لا يتم عرض هذا الحقل دائمًا، ومحتواه عرضة للتغيير.

ElevationStatus

رموز الحالة التي تعرضها الخدمة

  • ‫OK يشير إلى أنّ طلب البيانات من واجهة برمجة التطبيقات تم بنجاح.
  • DATA_NOT_AVAILABLE تشير إلى عدم توفّر بيانات للمواقع الجغرافية التي تم إدخالها
  • ‫INVALID_REQUEST يشير إلى أنّ طلب البيانات من واجهة برمجة التطبيقات تم تنسيقه بشكل غير صحيح.
  • OVER_DAILY_LIMIT تشير إلى أيّ مما يلي:
    • مفتاح واجهة برمجة التطبيقات غير متوفّر أو غير صالح.
    • لم يتم تفعيل الفوترة في حسابك.
    • تم تجاوز الحد الأقصى للاستخدام الذي فرضته بنفسك.
    • طريقة الدفع المقدَّمة لم تعُد صالحة (على سبيل المثال، انتهت صلاحية بطاقة الائتمان).
  • ‫OVER_QUERY_LIMIT تشير إلى أنّ مقدّم الطلب قد تجاوز الحصة.
  • ‫REQUEST_DENIED يشير إلى أنّ واجهة برمجة التطبيقات لم تكمِل الطلب.
  • ‫UNKNOWN_ERROR تشير إلى حدوث خطأ غير معروف.

عندما يكون رمز الحالة غير OK، قد يكون هناك حقل error_message إضافي ضمن عنصر استجابة Elevation. يحتوي هذا الحقل على معلومات أكثر تفصيلاً عن الأسباب وراء رمز الحالة المحدّد.

يحتوي الردّ على مصفوفة results تتضمّن العناصر التالية:

ElevationResult

الحقل مطلوب النوع الوصف
مطلوب الرقم

ارتفاع الموقع الجغرافي بالأمتار
مطلوب LatLngLiteral

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

لمزيد من المعلومات، يُرجى الاطّلاع على LatLngLiteral.

اختياري الرقم

القيمة التي تشير إلى الحد الأقصى للمسافة بين نقاط البيانات التي تم استقراء الارتفاع منها، بالأمتار. لن تظهر هذه السمة إذا كانت الدقة غير معروفة. يُرجى العِلم أنّ بيانات الارتفاع تصبح أكثر خشونة (قيم دقة أكبر) عند تمرير نقاط متعددة. للحصول على قيمة الارتفاع الأكثر دقة لنقطة معيّنة، يجب الاستعلام عنها بشكل مستقل.

LatLngLiteral

عنصر يصف موقعًا جغرافيًا محدّدًا بخطوط العرض والطول بالدرجات العشرية

الحقل مطلوب النوع الوصف
مطلوب الرقم

خط العرض بالدرجات العشرية
مطلوب الرقم

خط الطول بالدرجات العشرية

أمثلة على الارتفاع الموضعي

يطلب المثال التالي الارتفاع لمدينة دنفر، كولورادو، "مدينة مايل هاي":

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

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

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>