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

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

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

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

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

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

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

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

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

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

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

جميع الطلبات

key - (مطلوبة) مفتاح واجهة برمجة التطبيقات لتطبيقك يحدد هذا المفتاح تطبيقك لأغراض إدارة الحصص. تعرَّف على كيفية الحصول على مفتاح.

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

locations (سمة مطلوبة) لتحديد المواقع الجغرافية على سطح الأرض التي يتم من خلالها عرض بيانات الارتفاع تأخذ هذه المَعلمة إما موقعًا جغرافيًا واحدًا كزوج {latitude,longitude} مفصول بفواصل (مثل "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
مجموعة من الإحداثيات المشفّرة باستخدام خوارزمية Polyline المشفّرة : 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.

الردود المتعلّقة بالارتفاع

لكل طلب صالح، ستعرض خدمة "الارتفاع" استجابة "الارتفاع" بالتنسيق المشار إليه في عنوان 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