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

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

يتم إنشاء طلبات 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>.

ملاحظة: يجب أن تكون عناوين 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
  • مجموعة من الإحداثيات المرمّزة باستخدام خوارزمية Encoded Polyline: 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
  • الإحداثيات المرمّزة باستخدام خوارزمية Encoded Polyline: 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
  • الإحداثيات المرمّزة باستخدام خوارزمية Encoded Polyline: 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.

ردود بشأن الارتفاع

لكل طلب صالح، تعرض خدمة 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>

يعرض المثال التالي ردودًا متعدّدة (لـ "دنفر"، كولورادو و"وادي الموت"، كاليفورنيا).

يوضّح هذا الطلب كيفية استخدام العلامة 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'

يوضّح هذا الطلب كيفية استخدام علامة 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>