طلبات الارتفاع
يتم إنشاء طلبات 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 |
---|---|---|---|
| required | Array<ElevationResult> | See ElevationResult for more information. |
| required | ElevationStatus | See ElevationStatus for more information. |
| optional | string |
When the service returns a status code other than |
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 |
---|---|---|---|
| required | number | The elevation of the location in meters. |
| 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. |
| 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 |
---|---|---|---|
| required | number | Latitude in decimal degrees |
| 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>