محدودیت سرعت

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

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

درخواست‌ها

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

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

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

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

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

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

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

    این API روی شناسه‌های مکان ارائه شده، road-snapping انجام نمی‌دهد. می‌توانید یک درخواست 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 — آرایه‌ای از نقاط snapped. این آرایه فقط در صورتی وجود دارد که درخواست شامل پارامتر path باشد. هر نقطه شامل فیلدهای زیر است:
  • location — شامل مقدار latitude و longitude است.
  • originalIndex — یک عدد صحیح که مقدار متناظر در درخواست اصلی را نشان می‌دهد. هر مقدار در درخواست باید به یک مقدار snapped در پاسخ نگاشت شود. این مقادیر از 0 اندیس‌گذاری می‌شوند، بنابراین نقطه‌ای با originalIndex برابر با 4 ، مقدار snapped پنجمین طول/عرض جغرافیایی ارسالی به پارامتر 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"
    }
  ]
}

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

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

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

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

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

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

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