این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

درخواست ها و پاسخ های ارتفاع

درخواست های ارتفاع

درخواست های Elevation API به عنوان یک رشته URL ساخته می شوند. API داده های ارتفاع را برای مکان های روی زمین برمی گرداند. داده های مکان را به یکی از دو روش مشخص می کنید:

به عنوان مجموعه ای از یک یا چند locations .
به عنوان مجموعه ای از نقاط متصل در طول یک path .

هر یک از این رویکردها از مختصات طول و عرض جغرافیایی برای شناسایی مکان ها یا رئوس مسیر استفاده می کند. این سند فرمت مورد نیاز URL های API Elevation و پارامترهای موجود را شرح می دهد.

Elevation API داده ها را برای پرس و جوهای تک نقطه ای با بالاترین دقت ممکن برمی گرداند. پرس‌وجوهای دسته‌ای شامل مکان‌های مختلف ممکن است داده‌ها را با دقت کمتری برگردانند، به‌ویژه اگر مکان‌ها از هم جدا شده باشند، زیرا کمی هموارسازی داده‌ها رخ می‌دهد.

یک درخواست Elevation API به شکل زیر است:

https://maps.googleapis.com/maps/api/elevation/outputFormat?parameters

که در آن outputFormat ممکن است یکی از مقادیر زیر باشد:

json (توصیه می شود)، خروجی را در نشانه گذاری شی جاوا اسکریپت (JSON) نشان می دهد. یا
xml ، خروجی را در XML نشان می دهد که در یک گره <ElevationResponse> پیچیده شده است.

توجه : URL ها برای معتبر بودن باید به درستی کدگذاری شوند و برای همه سرویس های وب به 16384 کاراکتر محدود می شوند. هنگام ساخت URL های خود از این محدودیت آگاه باشید. توجه داشته باشید که مرورگرها، پروکسی ها و سرورهای مختلف ممکن است محدودیت کاراکتر URL متفاوتی نیز داشته باشند.

برای درخواست هایی که از کلید API استفاده می کنند، HTTPS لازم است.

درخواست پارامترها

درخواست‌ها به Elevation API از پارامترهای مختلفی بر اساس اینکه درخواست برای مکان‌های گسسته یا برای یک مسیر مرتب شده است، استفاده می‌کنند. برای مکان‌های مجزا، درخواست‌ها برای داده‌های مربوط به ارتفاع در مکان‌های خاص ارسال شده در درخواست. برای مسیرها، درخواست های ارتفاع به جای آن در طول مسیر داده شده نمونه برداری می شوند.

همانطور که در همه URL ها استاندارد است، پارامترها با استفاده از کاراکتر علامت ( & ) از هم جدا می شوند. لیست پارامترها و مقادیر احتمالی آنها در زیر نشان داده شده است.

همه درخواست ها

key — ( ضروری ) کلید API برنامه شما. این کلید درخواست شما را برای اهداف مدیریت سهمیه شناسایی می کند. نحوه دریافت کلید را بیاموزید.

درخواست های موضعی

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 داشته باشند. اگر مقدار طول و عرض جغرافیایی نامعتبر را مشخص کنید، درخواست شما به عنوان یک درخواست بد رد خواهد شد.

پاسخ های ارتفاعی

برای هر درخواست معتبر، سرویس Elevation یک پاسخ Elevation در قالب نشان داده شده در 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 اضافی در شیء پاسخ Elevation وجود داشته باشد. این فیلد حاوی اطلاعات دقیق تری در مورد دلایل پشت کد وضعیت داده شده است.

پاسخ شامل یک آرایه 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>

مثال زیر چندین پاسخ را نشان می دهد (برای Denver، CO و برای Death Valley، CA).

این درخواست با استفاده از پرچم output JSON نشان می دهد:

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