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

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

يتم إنشاء طلبات البيانات من واجهة برمجة التطبيقات للارتفاع كسلسلة عنوان 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، يتم فصل المعلَمات باستخدام حرف العطف اللاتيني (&amp;). تتم الإشارة إلى قائمة المعلمات وقيمها المحتملة أدناه.

جميع الطلبات

  • 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

FieldRequiredTypeDescription
required Array<ElevationResult> See ElevationResult for more information.
requiredElevationStatus See ElevationStatus for more information.
optionalstring

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

FieldRequiredTypeDescription
requirednumber

The elevation of the location in meters.

requiredLatLngLiteral

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.

optionalnumber

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.

FieldRequiredTypeDescription
requirednumber

Latitude in decimal degrees

requirednumber

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>