محدودیت‌های سرعت

‫Roads API محدودیت سرعت را برای بخش‌های جاده‌ای داده‌شده برمی‌گرداند. در مورد بخش‌های جاده‌ای با محدودیت‌های سرعت متغیر، حداکثر محدودیت سرعت برای خودروها در آن بخش برگردانده می‌شود.

دقت داده‌های حد سرعت که Roads API برمی‌گرداند تضمین نمی‌شود. داده‌های ارائه شده درباره سرعت مجاز هم‌زمان نیست و ممکن است تخمینی، نادرست، ناقص، یا قدیمی باشد. برای دیدن مناطقی که داده‌های حد سرعت در آن‌ها دردسترس است، جزئیات پوشش را ببینید.

درخواست‌ها

درخواست‌های مربوط به محدودیت سرعت را بااستفاده از HTTPS در قالب زیر ارسال کنید:

https://roads.googleapis.com/v1/speedLimits?parameters&key=YOUR_API_KEY

استفاده از پارامتر

پارامترهای الزامی

• پارامتر path یا placeId.

  • path — فهرستی از حداکثر ۱۰۰ جفت طول/عرض جغرافیایی که نشان‌دهنده یک مسیر است. مقادیر عرض و طول جغرافیایی باید با کاما از هم جدا شوند. جفت‌های عرض جغرافیایی/طول جغرافیایی باید با نویسه خط عمودی «|» از هم جدا شوند. وقتی پارامتر path را ارائه می‌کنید، API ابتدا مسیر را به محتمل‌ترین جاده‌ای که خودرو در آن حرکت کرده است می‌چسباند (همان‌طور که برای درخواست snapToRoads انجام می‌دهد)، سپس محدودیت سرعت را برای بخش مربوطه جاده تعیین می‌کند. اگر نمی‌خواهید «میانای برنامه‌سازی کاربردی» مسیر را به هم بچسباند، باید پارامتر placeId را همان‌طور که در زیر توضیح داده شده است بگذرانید. مثال زیر پارامتر path را با سه جفت طول/عرض جغرافیایی نشان می‌دهد: path=60.170880,24.942795|60.170879,24.942796|60.170877,24.942796.

  • placeId — شناسه(های) مکان نشان‌دهنده یک یا چند بخش جاده. مطمئن شوید هر شناسه مکان به بخشی از جاده اشاره می‌کند و نه به نوع دیگری از مکان. می‌توانید حداکثر ۱۰۰ شناسه مکان را با هر درخواست ارسال کنید. پاسخ شامل محدودیت سرعت برای هر شناسه مکان در درخواست است.

    این API چسباندن به جاده را روی شناسه‌های مکان ارائه‌شده انجام نمی‌دهد. می‌توانید درخواست snapToRoads یا nearestRoads ارسال کنید تا شناسه‌های مکان مربوطه را پیدا کنید و سپس آن‌ها را به‌عنوان ورودی به درخواست speedLimits ارائه دهید. مثال زیر پارامتر placeId را با دو شناسه مکان نشان می‌دهد: placeId=ChIJs5ydyTiuEmsR0fRSlU0C7k0&placeId=ChIJW__r4ERXzpQRgkeRL6P0m3Y

• key — کلید میانای برنامه‌سازی کاربردی برنامه شما. برنامه شما باید هربار که درخواستی به Roads API ارسال می‌کند، با افزودن کلید API به هر درخواست، خود را معرفی کند. با نحوه دریافت کلید آشنا شوید.

پارامترهای اختیاری

• units — اینکه آیا محدودیت‌های سرعت برحسب کیلومتر یا مایل در ساعت برگردانده شود. این گزینه را می‌توان روی KPH یا MPH تنظیم کرد. پیش‌فرض KPH است.

پاسخ‌ها

عناصر زیر ممکن است در پاسخ speedLimits وجود داشته باشد:

• speedLimits — آرایه‌ای از فراداده‌های جاده. هر عنصر از فیلدهای زیر تشکیل شده است:
  • placeId — شناسه یکتای مکان. همه شناسه‌های مکان برگشت‌داده‌شده توسط Roads API با بخش‌های جاده مطابقت خواهد داشت.
  • speedLimit — سقف سرعت مجاز برای آن بخش جاده.
  • ‫units — یا KPH یا MPH را برمی‌گرداند.
• ‫snappedPoints — آرایه‌ای از نقطه‌های چسبیده. این آرایه فقط درصورتی وجود دارد که درخواست حاوی پارامتر path باشد. هر نقطه از فیلدهای زیر تشکیل شده است:
  • ‫location — حاوی مقدار latitude و longitude است.
  • originalIndex — عدد صحیحی که نشان‌دهنده مقدار مربوطه در درخواست اصلی است. هر مقدار در درخواست باید به مقدار چسبیده در پاسخ نگاشت شود. این مقادیر از 0 فهرست‌بندی می‌شوند، بنابراین نقطه‌ای با originalIndex برابر با 4 مقدار چسبیده پنجمین عرض/طول جغرافیایی منتقل‌شده به پارامتر path خواهد بود.
  • placeId — شناسه یکتای مکان. همه شناسه‌های مکان برگشتی از Roads API با بخش‌های جاده مطابقت خواهد داشت. placeId را می‌توان در درخواست حدود سرعت ارسال کرد تا حد سرعت در آن بخش جاده تعیین شود.
• warning_message — رشته‌ای حاوی هشداری که برای کاربر قابل‌مشاهده است.

درخواست نمونه بااستفاده از مسیر

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

درخواست

https://roads.googleapis.com/v1/speedLimits?path=38.75807927603043,-9.03741754643809|38.6896537,-9.1770515|41.1399289,-8.6094075&key=YOUR_API_KEY

پاسخ

{
  speedLimits:
  [
    {
      placeId: "ChIJX12duJAwGQ0Ra0d4Oi4jOGE",
      speedLimit: 105,
      units: "KPH"
    },
    {
      placeId: "ChIJLQcticc0GQ0RoiNZJVa5GxU",
      speedLimit: 70,
      units: "KPH"
    },
    {
      placeId: "ChIJJ4vQRudkJA0RpednU70A-5M",
      speedLimit: 55,
      units: "KPH"
    }
  ],
  snappedPoints:
  [
    {
      location:
      {
        latitude: 38.75807927603043,
        longitude: -9.037417546438084
      },
      originalIndex: 0,
      placeId: "ChIJX12duJAwGQ0Ra0d4Oi4jOGE"
    },
    {
      location:
      {
        latitude: 38.689653701836896,
        longitude: -9.177051486847693
      },
      originalIndex: 1,
      placeId: "ChIJLQcticc0GQ0RoiNZJVa5GxU"
    },
    {
      location:
      {
        latitude: 41.13993011767777,
        longitude: -8.609400794783655
      },
      originalIndex: 2,
      placeId: "ChIJJ4vQRudkJA0RpednU70A-5M"
    }
  ],
  warningMessage: "Input path is too sparse. You should provide a path where consecutive points are closer to each other. Refer to the 'path' parameter in Google Roads API documentation."
}

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

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

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

مثال زیر محدودیت‌های سرعت را برای برخی‌از بخش‌های جاده‌ای که از روی پل واسکو دا گاما در لیسبون، پرتغال می‌گذرند درخواست می‌کند.

درخواست

https://roads.googleapis.com/v1/speedLimits?placeId=ChIJX12duJAwGQ0Ra0d4Oi4jOGE&placeId=ChIJLQcticc0GQ0RoiNZJVa5GxU&placeId=ChIJJ4vQRudkJA0RpednU70A-5M&key=YOUR_API_KEY

پاسخ

{
  "speedLimits": [
    {
      placeId: "ChIJX12duJAwGQ0Ra0d4Oi4jOGE",
      speedLimit: 105,
      units: "KPH"
    },
    {
      placeId: "ChIJLQcticc0GQ0RoiNZJVa5GxU",
      speedLimit: 70,
      units: "KPH"
    },
    {
      placeId: "ChIJJ4vQRudkJA0RpednU70A-5M",
      speedLimit: 55,
      units: "KPH"
    }
  ]
}

توصیه‌های استفاده

برای به‌حداقل رساندن حجم تماس‌ها با سرویس «محدودیت سرعت»، توصیه می‌کنیم مکان‌های دارایی‌هایتان را در فواصل ۵ تا ۱۵ دقیقه‌ای نمونه‌برداری کنید (مقدار دقیق به سرعتی که دارایی درحال حرکت است بستگی دارد). اگر دارایی ثابت باشد، یک نمونه مکان کافی است (نیازی به انجام چندین تماس نیست).

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

چرا برخی/همه محدودیت‌های سرعت وجود ندارد؟

رایج‌ترین دلیل برای نبود speedLimits درخواست سرعت مجاز مکانی است که قطعه جاده نیست.

مثال بالا از پل «واسکو دا گاما» برای نشان دادن مفاهیم استفاده می‌کند؛ این پل از جاده E90 که از روی رودخانه «تژو» می‌گذرد پشتیبانی می‌کند. خود پل دارای شناسه مکان ChIJUzt97ZEwGQ0RM1JzQfqoDtU است. اولین بخش جاده در پاسخ بالا بخشی از جاده E90 است و شناسه مکان آن ChIJX12duJAwGQ0Ra0d4Oi4jOGE است. در درخواست نمونه، اگر شناسه مکان جاده را با شناسه مکان پل جایگزین کنید، در پاسخ فقط دو حد سرعت در آرایه speedLimits وجود خواهد داشت زیرا شناسه مکان پل به بخش جاده‌ای مجزایی اشاره نمی‌کند. علاوه‌براین، اگر هیچ‌یک از شناسه‌های مکان مربوط به بخش‌های جاده نباشد، پاسخ حاوی هیچ‌گونه محدودیت سرعتی نخواهد بود.

هنگام درخواست‌های حد سرعت بااستفاده از شناسه‌های مکان، مطمئن شوید هر شناسه مکان به یک بخش از جاده اشاره می‌کند و نه به نوع دیگری از مکان. شناسه‌های مکان برای بخش‌های جاده‌ای تکی بهتر است بااستفاده از درخواست‌های snapToRoads یا nearestRoads بازیابی شوند، که هرکدام می‌توانند چندین شناسه مکان را از یک تماس برگردانند.

اگر بخشی از جاده حد مجاز سرعت متفاوتی برای خودروها و کامیون‌ها داشته باشد چه؟

‫Roads API حداکثر حد مجاز سرعت اعلام‌شده را فقط برای خودروها برمی‌گرداند.