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