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

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 ارسال می‌کند، با گنجاندن کلید میانای برنامه‌سازی کاربردی در هر درخواست، هویت خود را مشخص کند. با نحوه دریافت کلید آشنا شوید.

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

• 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"
    }
  ]
}

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

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

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

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

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

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

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

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

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