تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

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

يظهر طلب Elitation API على النحو التالي:

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

حيث قد تكون outputFormat أيًّا من القيمتَين التاليتَين:

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

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

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

معلمات الطلب

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

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

جميع الطلبات

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

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

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

ElevationResponse

Field	Required	Type	Description
`results`	required	Array<ElevationResult>	See ElevationResult for more information.
`status`	required	ElevationStatus	See ElevationStatus for more information.
`error_message`	optional	string	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 إضافي ضمن كائن استجابة "الارتفاع". يحتوي هذا الحقل على معلومات أكثر تفصيلاً حول الأسباب الكامنة وراء رمز الحالة المعين.

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

ElevationResult

Field	Required	Type	Description
`elevation`	required	number	The elevation of the location in meters.
`location`	required	LatLngLiteral	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.
`resolution`	optional	number	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.

Field	Required	Type	Description
`lat`	required	number	Latitude in decimal degrees
`lng`	required	number	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>

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

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

معلمات الطلب

جميع الطلبات

طلبات تحديد الموضع

طلبات المسارات المستندة إلى عينات

تحديد المواقع الجغرافية

تحديد المسارات

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

ElevationResponse

`results`

`status`

`error_message`

ElevationStatus

ElevationResult

`elevation`

`location`

`resolution`

LatLngLiteral

`lat`

`lng`

أمثلة على المسقط الرأسي

عنوان URL

cURL

JSON

XML

عنوان URL

cURL

JSON

XML

عنوان URL

cURL

JSON

XML