محدودیت سرعت

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

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

درخواست ها

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

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

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

پارامترهای مورد نیاز

  • یک path یا یک پارامتر placeId .
    • path - لیستی از حداکثر 100 جفت طول و عرض جغرافیایی که یک مسیر را نشان می دهد. مقادیر طول و عرض جغرافیایی باید با کاما از هم جدا شوند. جفت طول و عرض جغرافیایی باید با کاراکتر لوله از هم جدا شوند: "|". هنگامی که پارامتر path را ارائه می کنید، API ابتدا مسیر را به محتمل ترین جاده ای که وسیله نقلیه طی کرده است می بندد (همانطور که برای درخواست snapToRoads انجام می دهد)، سپس محدودیت سرعت را برای بخش جاده مربوطه تعیین می کند. اگر نمی‌خواهید API مسیر را قطع کند، باید یک پارامتر placeId را همانطور که در زیر توضیح داده شده است ارسال کنید. مثال زیر پارامتر path را با سه جفت طول و عرض جغرافیایی نشان می‌دهد: path=60.170880,24.942795|60.170879,24.942796|60.170877,24.942796 .
    • placeId - شناسه (های) مکان که یک یا چند بخش جاده را نشان می دهد. مطمئن شوید که شناسه هر مکان به یک بخش جاده اشاره دارد و نه یک مکان متفاوت. با هر درخواست می توانید تا 100 شناسه مکان را ارسال کنید. API بر روی شناسه‌های مکان ارائه‌شده، جابجایی جاده را انجام نمی‌دهد. پاسخ شامل محدودیت سرعت برای هر شناسه مکان در درخواست است. می‌توانید یک درخواست snapToRoads یا nearestRoads ارسال کنید تا شناسه‌های مکان مربوطه را بیابید و سپس آنها را به عنوان ورودی به درخواست speedLimits ارائه دهید. مثال زیر پارامتر placeId را با دو شناسه مکان نشان می دهد: placeId=ChIJX12duJAwGQ0Ra0d4Oi4jOGE&placeId=ChIJLQcticc0GQ0RoiNZJVa5GxU
  • key - کلید API برنامه شما. برنامه شما باید هر بار که درخواستی به 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 مقدار قطع شده 5مین طول و عرض جغرافیایی خواهد بود که به پارامتر 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"
    }
  ]
}

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

برای به حداقل رساندن حجم تماس با سرویس محدودیت سرعت، توصیه می کنیم مکان دارایی های خود را در فواصل زمانی 5 تا 15 دقیقه ای نمونه برداری کنید (مقدار دقیق بستگی به سرعت حرکت دارایی دارد). اگر دارایی ثابت باشد، یک نمونه مکان کافی است (نیازی به برقراری تماس های متعدد نیست).

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

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

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

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

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