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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

پاسخ ارتفاعی

میدان مورد نیاز نوع توضیحات
مورد نیاز آرایه < نتیجه ارتفاع > برای اطلاعات بیشتر به ElevationResult مراجعه کنید.
مورد نیاز وضعیت ارتفاع برای اطلاعات بیشتر به وضعیت ارتفاع مراجعه کنید.
اختیاری رشته

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

وضعیت ارتفاع

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

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

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

پاسخ شامل یک آرایه results با عناصر زیر است:

نتیجه ارتفاع

میدان مورد نیاز نوع توضیحات
مورد نیاز شماره

ارتفاع محل بر حسب متر.

مورد نیاز لات‌لنگ‌لیترال

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

برای اطلاعات بیشتر به LatLngLiteral مراجعه کنید.

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

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

لات‌لنگ‌لیترال

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

میدان مورد نیاز نوع توضیحات
مورد نیاز شماره

عرض جغرافیایی بر حسب درجه اعشاری

مورد نیاز شماره

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

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

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

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

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>