تعرض Roads API حد السرعة المنشور لجزء معين من الطريق. في حالة قطاعات الطرق ذات حدود السرعة المتغيرة، يتم إرجاع حد السرعة الافتراضي للجزء.
لا يمكن ضمان دقة بيانات حد السرعة التي تعرضها دالة Roads API. بيانات حد السرعة التي تم تقديمها ليست في الوقت الفعلي، وقد يتم تقديرها و/أو غير دقيقة و/أو غير كاملة و/أو قديمة. يمكنك الاطّلاع على تفاصيل التغطية لمعرفة المناطق التي تتوفّر فيها بيانات حدود السرعة.
الكائن Requests
يجب إرسال طلب حدود السرعة عبر HTTPS، ويكون على النحو التالي:
https://roads.googleapis.com/v1/speedLimits?parameters&key=YOUR_API_KEY
استخدام المعلمة
المَعلمات المطلوبة
- المعلَمة
path
أوplaceId
.path
— قائمة تضم ما يصل إلى 100 زوج من خطوط الطول/العرض يمثّل مسارًا. يجب فصل قيم خطوط الطول والعرض بفواصل. يجب فصل أزواج خطوط الطول والعرض بحرف الشرطة الرأسية: "|". عند تقديم المَعلمةpath
، تضبط واجهة برمجة التطبيقات أولاً المسار إلى الطريق المرجّح أن تسلكها مركبة (كما هو الحال مع طلبsnapToRoads
)، ثم تحدّد حد السرعة لجزء الطريق ذي الصلة. إذا كنت لا تريد من واجهة برمجة التطبيقات أن تلتقط المسار، عليك تمرير معلَمةplaceId
كما هو موضّح أدناه. يعرض المثال التالي المعلَمةpath
مع ثلاثة أزواج من خطوط الطول/العرض:path=60.170880,24.942795|60.170879,24.942796|60.170877,24.942796
.placeId
— أرقام تعريف الأماكن التي تمثل قطاعًا واحدًا أو أكثر من الطرق. تأكد من أن كل معرّف مكان يشير إلى جزء من الطريق وليس إلى نوع مختلف من الأماكن. يمكنك تمرير ما يصل إلى 100 معرّف مكان مع كل طلب. لا تُظهر واجهة برمجة التطبيقات لقطات لأرقام تعريف الأماكن التي تم إدخالها. يتضمن الرد حدًا لسرعة كل رقم تعريف مكان في الطلب. يمكنك إرسال طلبsnapToRoads
أوnearestRoads
للعثور على أرقام تعريف الأماكن ذات الصلة ثم تقديمها كإدخال في طلبspeedLimits
. يوضّح المثال التالي المَعلمةplaceId
مع رقمَي تعريف مكانَين:placeId=ChIJX12duJAwGQ0Ra0d4Oi4jOGE&placeId=ChIJLQcticc0GQ0RoiNZJVa5GxU
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
. عند تمرير معرّفات الأماكن، تعرض واجهة برمجة التطبيقات
حد السرعة لجزء الطريق الذي يمثله كل معرّف مكان. لا تُطبق واجهة برمجة التطبيقات أي مقاطع طريق على معرّفات الأماكن المقدمة.
يطلب المثال التالي حدود السرعة لبعض أجزاء الطرق التي تعبر جسر فاسكو دا غاما في لشبونة بالبرتغال.
طلب
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 دقيقة (تعتمد القيمة الدقيقة على سرعة انتقال مادة العرض). إذا كانت مادة العرض ثابتة، يكفي استخدام عينة واحدة من الموقع الجغرافي (لا توجد حاجة لإجراء عدة استدعاءات).
لتقليل وقت الاستجابة الإجمالي، ننصح بالاتصال بخدمة "الحدّ الأقصى للسرعة" بعد تجميع بعض البيانات، بدلاً من طلب البيانات من واجهة برمجة التطبيقات في كل مرّة يتم تلقّي موقع مادة عرض الجوّال.
لماذا هناك بعض/جميع حدود السرعة غير موجودة؟
السبب الأكثر شيوعًا لعدم توفّر speedLimits
هو طلب ضبط حدّ السرعة
لمكان ليس جزءًا من الطريق.
يستخدم المثال أعلاه جسر فاسكو دا غاما لتوضيح المفاهيم؛
يدعم الجسر طريق عبور E90 فوق نهر ريو تيجو. رقم تعريف المكان هو ChIJUzt97ZEwGQ0RM1JzQfqoDtU. جزء الطريق الأول في الاستجابة أعلاه هو جزء من الطريق E90 ويحتوي على معرّف المكان
ChIJX12duJAwGQ0Ra0d4Oi4jOGE. في نموذج الطلب، إذا استبدلت معرّف مكان
الطريق بمعرّف مكان الجسر، سيكون هناك في الاستجابة
حدان للسرعة في صفيف speedLimits
لأن معرّف مكان
الجسر لا يشير إلى جزء فردي من الطريق. علاوة على ذلك، إذا لم يكن أي من معرفات الأماكن مخصصة لأجزاء الطرق، فلن تحتوي الاستجابة على أي حدود للسرعة.
عند تقديم طلبات حدود السرعة باستخدام معرّفات الأماكن، تأكد من أن كل رقم تعريف مكان يشير إلى قطاع من الطريق وليس إلى نوع مختلف من الأماكن. من الأفضل استرداد معرّفات الأماكن لأجزاء الطرق الفردية باستخدام طلبات snapToRoads
أو nearestRoads
، حيث يمكن لأي منهما عرض معرّفات أماكن متعددة من مكالمة واحدة.