درخواست‌ها و پاسخ‌های ارتقا

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

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

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

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

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

درخواست Elevation API به‌صورت زیر است:

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

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

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

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

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

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

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

کل درخواست‌ها

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

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

  • ‫locations (الزامی) مکان(های) روی زمین را که داده‌های ارتفاع از آن‌ها برگردانده می‌شود تعریف می‌کند. این پارامتر یا یک مکان تکی را به‌صورت جفت {عرض جغرافیایی، طول جغرافیایی} جداشده با کاما (مثلاً «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 داشته باشند. اگر مقدار طول یا عرض جغرافیایی نامعتبری را مشخص کنید، درخواست شما به‌عنوان درخواست بد رد خواهد شد.

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

می‌توانید تا ۵۱۲ مختصات را در یک آرایه یا چندخطی کدگذاری‌شده ارسال کنید، درحالی‌که هنوز یک نشانی وب معتبر می‌سازید. توجه داشته باشید که هنگام ارسال چندین مختصات، دقت هر داده برگشتی ممکن است وضوح کمتری نسبت به زمانی داشته باشد که داده‌ها برای یک مختصات درخواست می‌شوند. فراتر رفتن از ۵۱۲ نقطه یا مختصات در پارامترهای «مکان‌ها» یا «مسیر» پاسخ INVALID_REQUEST را برمی‌گرداند.

پاسخ‌های ارتقا

  • آرایه‌ای از دو یا چند رشته نوشتاری مختصات جداشده با کاما که بااستفاده از نویسه خط عمودی («|») از هم جدا شده‌اند: 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 داشته باشد. اگر مقدار عرض یا طول جغرافیایی نامعتبری را مشخص کنید، درخواست شما به‌عنوان درخواست بد رد خواهد شد.

می‌توانید تا ۵۱۲ مختصات را در یک آرایه یا چندخطی کدگذاری‌شده ارسال کنید، درحالی‌که هنوز یک نشانی وب معتبر می‌سازید. توجه داشته باشید که هنگام ارسال چندین مختصات، دقت هر داده برگشتی ممکن است وضوح کمتری نسبت به زمانی داشته باشد که داده‌ها برای یک مختصات درخواست می‌شوند. فراتر رفتن از ۵۱۲ نقطه یا مختصات در پارامترهای «مکان‌ها» یا «مسیر» پاسخ INVALID_REQUEST را برمی‌گرداند.

پاسخ‌های ارتقا

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

ElevationResponse

فیلد الزامی نوع شرح
الزامی Array<ElevationResult> برای اطلاعات بیشتر، ElevationResult را ببینید.
الزامی ElevationStatus برای اطلاعات بیشتر، ElevationStatus را ببینید.
اختیاری رشته

وقتی سرویس کد وضعیتی غیراز OK برمی‌گرداند، ممکن است فیلد error_message دیگری در شیء پاسخ وجود داشته باشد. این فیلد حاوی اطلاعات دقیق‌تری درباره دلایل پشت رمز وضعیت داده‌شده است. این فیلد همیشه برگردانده نمی‌شود و محتوای آن ممکن است تغییر کند.

ElevationStatus

رمزهای وضعیت برگردانده‌شده توسط سرویس.

  • OK که نشان می‌دهد درخواست API موفقیت‌آمیز بوده است.
  • DATA_NOT_AVAILABLE نشان می‌دهد که هیچ داده‌ای برای مکان‌های ورودی دردسترس نیست.
  • INVALID_REQUEST نشان می‌دهد که درخواست میانای برنامه‌سازی کاربردی ناقص بوده است.
  • OVER_DAILY_LIMIT که نشان‌دهنده هریک از موارد زیر باشد:
    • کلید میانای برنامه‌سازی کاربردی وجود ندارد یا نامعتبر است.
    • صدور صورت‌حساب در حسابتان فعال نشده است.
    • از سقف استفاده‌ای که خودتان تعیین کرده‌اید فراتر رفته‌اید.
    • روش پرداخت ارائه‌شده دیگر معتبر نیست (برای مثال، کارت اعتباری منقضی شده است).
  • OVER_QUERY_LIMIT نشان می‌دهد که درخواست‌کننده از سهمیه فراتر رفته است.
  • REQUEST_DENIED که نشان می‌دهد میانای برنامه‌سازی کاربردی درخواست را تکمیل نکرده است.
  • UNKNOWN_ERROR که نشان‌دهنده خطای ناشناخته است.

وقتی کد وضعیت چیزی غیراز OK باشد، ممکن است فیلد error_message دیگری در شیء پاسخ Elevation وجود داشته باشد. این فیلد حاوی اطلاعات دقیق‌تر درباره دلایل پشت کد وضعیت داده‌شده است.

پاسخ حاوی آرایه results با عناصر زیر است:

ElevationResult

فیلد الزامی نوع شرح
الزامی شماره

ارتفاع مکان به متر.
الزامی LatLngLiteral

عنصر مکان موقعیتی که داده‌های ارتفاع آن درحال محاسبه است. توجه داشته باشید که برای درخواست‌های مسیر، مجموعه عناصر مکان شامل نقاط نمونه‌برداری‌شده درطول مسیر خواهد بود.

برای اطلاعات بیشتر، LatLngLiteral را ببینید.

اختیاری شماره

مقداری که حداکثر فاصله بین نقاط داده را نشان می‌دهد که ارتفاع از آن درون‌یابی شده است، به متر. اگر وضوح مشخص نباشد، این ویژگی وجود نخواهد داشت. توجه داشته باشید که وقتی چند نقطه ارسال می‌شود، داده‌های ارتفاع درشت‌تر (مقادیر وضوح بزرگ‌تر) می‌شود. برای به‌دست آوردن دقیق‌ترین مقدار ارتفاع برای یک نقطه، باید به‌طور مستقل پرس‌وجو شود.

LatLngLiteral

شیئی که مکان خاصی را با عرض جغرافیایی و طول جغرافیایی در درجه‌های اعشاری توصیف می‌کند.

فیلد الزامی نوع شرح
الزامی شماره

عرض جغرافیایی به درجه اعشاری
الزامی شماره

طول جغرافیایی به درجه اعشاری

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

مثال زیر ارتفاع دنور، کلرادو، «شهر مایل های» را درخواست می‌کند:

نشانی وب

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 را نشان می‌دهد:

نشانی وب

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'

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

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

نشانی وب

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>