تعرض 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
، ويمكن لأي منهما عرض أرقام تعريفية متعددة للأماكن من مكالمة واحدة.