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

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

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

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

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

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

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