طلبات الارتفاع
يتم إنشاء طلبات البيانات من واجهة برمجة التطبيقات للارتفاع كسلسلة عنوان URL. تعرض واجهة برمجة التطبيقات بيانات الارتفاع للمواقع على الأرض. يمكنك تحديد بيانات الموقع بإحدى طريقتين:
- كمجموعة من
locations
واحدة أو أكثر. - كسلسلة من النقاط المتصلة على طول
path
.
يستخدم أي من هذين الأسلوبين إحداثيات خطوط الطول والعرض لتحديد المواقع أو رؤوس المسارات. يصف هذا المستند التنسيق المطلوب لعناوين URL لواجهة برمجة تطبيقات الارتفاع والمعلمات المتاحة.
تعرض واجهة برمجة التطبيقات Elevation API بيانات لطلبات البحث ذات النقطة الواحدة بأعلى دقة ممكنة. قد تعرض طلبات البحث المجمّعة التي تتضمّن مواقع جغرافية متعددة بيانات بدقة أقل، خاصةً إذا كانت المواقع الجغرافية متباعدة، أثناء حدوث بعض تجانس البيانات.
يتخذ طلب البيانات من واجهة برمجة التطبيقات Elevation بالشكل التالي:
https://maps.googleapis.com/maps/api/elevation/outputFormat?parameters
حيث يمكن أن تكون السمة outputFormat
إحدى القيمتين التاليتين:
json
(يُنصح بها)، تشير إلى الإخراج في JavaScript Object Notation (JSON)، أو- وتشير القيمة
xml
إلى الناتج في XML، الملفوفًا في عقدة<ElevationResponse>
.
ملاحظة: يجب ترميز عناوين URL بشكل صحيح لتكون صالحة وتقتصر على 16384 حرفًا في جميع خدمات الويب. انتبِه إلى هذا الحد الأقصى المسموح به عند إنشاء عناوين URL. لاحظ أيضًا أن المتصفحات والخوادم الوكيلة والخوادم المختلفة قد تتضمن عددًا مختلفًا من الأحرف المسموح بها لعناوين URL أيضًا.
يجب استخدام HTTPS للطلبات التي تستخدم مفتاح واجهة برمجة التطبيقات.
مَعلمات الطلب
تستخدم الطلبات إلى واجهة برمجة التطبيقات للارتفاع معلمات مختلفة بناءً على ما إذا كان الطلب بخصوص مواقع منفصلة أو لمسار طلب. بالنسبة إلى المواقع المنفصلة، تعرض طلبات الارتفاع بيانات حول المواقع المحددة التي تم تمريرها في الطلب، أما بالنسبة إلى المسارات، فيتم أخذ عينات من طلبات الارتفاع على طول المسار المحدد.
وكما هو الحال في جميع عناوين 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
- مجموعة من الإحداثيات المرمّزة باستخدام خوارزمية الخطوط المتعددة المشفّرة:
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 |
أمثلة على الارتفاع الموضعي
يطلب المثال التالي المسقط الرأسي لمدينة دنفر، كولورادو، و "Mile High City" بتنسيق 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>