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

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

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

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

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

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

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

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

معلمات الطلب

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