طلبات الارتفاع
يتم إنشاء طلبات 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 |
---|---|---|---|
| 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>