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

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

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

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

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

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

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

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

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

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

json (توصیه می‌شود)، خروجی را در قالب نشانه‌گذاری شیء جاوا اسکریپت (JSON) نشان می‌دهد؛ یا
xml ، خروجی در XML را نشان می‌دهد که درون یک گره <ElevationResponse> قرار گرفته است.

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

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

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

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

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

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

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

درخواست‌های موقعیتی

locations ( الزامی ) مکان(هایی) روی زمین را تعریف می‌کند که از آنجا داده‌های ارتفاع بازگردانده می‌شود. این پارامتر یا یک مکان واحد را به عنوان یک جفت {latitude,longitude} که با کاما از هم جدا شده‌اند (مثلاً "40.714728,-73.998672") یا چندین جفت عرض/طول جغرافیایی را که به عنوان یک آرایه یا به عنوان یک چندخطی کدگذاری شده ارسال می‌شوند، دریافت می‌کند. برای این پارامتر خاص، محدودیت ۵۱۲ نقطه وجود دارد. برای اطلاعات بیشتر، به بخش «مشخص کردن مکان‌ها» در زیر مراجعه کنید.

درخواست‌های مسیر نمونه‌برداری شده

path ( الزامی ) مسیری را روی زمین تعریف می‌کند که داده‌های ارتفاع از آن برگردانده می‌شود. این پارامتر مجموعه‌ای از دو یا چند جفت مرتب {عرض جغرافیایی، طول جغرافیایی} را تعریف می‌کند که مسیری را در امتداد سطح زمین تعریف می‌کنند. این پارامتر باید همراه با پارامتر samples که در زیر توضیح داده شده است، استفاده شود. برای این پارامتر خاص، محدودیت ۵۱۲ نقطه وجود دارد. برای اطلاعات بیشتر، به بخش تعیین مسیرها در زیر مراجعه کنید.
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 را بگیرند. اگر مقدار عرض یا طول جغرافیایی نامعتبری را مشخص کنید، درخواست شما به عنوان یک درخواست نامناسب رد خواهد شد.

شما می‌توانید تا ۵۱۲ مختصات را در یک آرایه یا چندخطی کدگذاری شده ارسال کنید، در حالی که همچنان یک URL معتبر می‌سازید. توجه داشته باشید که هنگام ارسال چندین مختصات، دقت هر داده برگشتی ممکن است نسبت به درخواست داده برای یک مختصات واحد، وضوح کمتری داشته باشد. بیش از ۵۱۲ نقطه یا مختصات در پارامترهای '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 را بگیرند. اگر مقدار عرض یا طول جغرافیایی نامعتبری را مشخص کنید، درخواست شما به عنوان یک درخواست نامناسب رد خواهد شد.

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

برای هر درخواست معتبر، سرویس 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 درخواست می‌کند:

آدرس اینترنتی

https://maps.googleapis.com/maps/api/elevation/json
  ?locations=39.7391536%2C-104.9847034
  &key=YOUR_API_KEY

حلقه

curl -L -X GET 'https://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536%2C-104.9847034&key=YOUR_API_KEY'

جی‌سون

{
  "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>

مثال زیر چندین پاسخ را نشان می‌دهد (برای دنور، کلرادو و برای دث ولی، کالیفرنیا).

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

آدرس اینترنتی

https://maps.googleapis.com/maps/api/elevation/json
  ?locations=39.7391536%2C-104.9847034%7C36.455556%2C-116.866667
  &key=YOUR_API_KEY

حلقه

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، تب‌های زیر را انتخاب کنید.

جی‌سون

{
  "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 درخواست می‌کنیم، به طوری که شامل دو نقطه پایانی و نقطه میانی باشد.

آدرس اینترنتی

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 -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'

جی‌سون

{
  "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`

نمونه‌هایی از ارتفاع موقعیتی

آدرس اینترنتی

حلقه

جی‌سون

XML

آدرس اینترنتی

حلقه

جی‌سون

XML

آدرس اینترنتی

حلقه

جی‌سون

XML

درخواست ها و پاسخ های ارتفاع با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

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

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

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

درخواست‌های موقعیتی

درخواست‌های مسیر نمونه‌برداری شده

مشخص کردن مکان‌ها

مشخص کردن مسیرها

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

ElevationResponse

results

status

error_message

ElevationStatus

ElevationResult

elevation

location

resolution

LatLngLiteral

lat

lng

نمونه‌هایی از ارتفاع موقعیتی

آدرس اینترنتی

حلقه

جی‌سون

XML

آدرس اینترنتی

حلقه

جی‌سون

XML

آدرس اینترنتی

حلقه

جی‌سون

XML

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

`results`

`status`

`error_message`

`elevation`

`location`

`resolution`

`lat`

`lng`