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

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

يتم إنشاء طلبات Elevation API كسلسلة عناوين 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 بشكل صحيح لتكون صالحة، ويقتصر عدد الأحرف فيها على 16384 حرفًا لجميع خدمات الويب. يُرجى الانتباه إلى هذا الحدّ عند إنشاء عناوين URL. تجدر الإشارة إلى أنّ المتصفحات والوكلاء والخوادم المختلفة قد يكون لها أيضًا حدود مختلفة لعدد أحرف عناوين URL.

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

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

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

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

جميع الطلبات

الطلبات المستندة إلى الموضع

  • 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 نقطة أو إحداثية في المعلَمتَين "locations" أو "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 نقطة أو إحداثية في المعلَمتَين "locations" أو "path" إلى عرض استجابة 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 نقطة أو إحداثية في المعلَمتَين "locations" أو "path" إلى عرض استجابة INVALID_REQUEST.

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

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

تحتوي الاستجابة على مصفوفة 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>

يعرض المثال التالي استجابات متعدّدة (لدنفر في كولورادو و"وادي الموت" في كاليفورنيا).

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