تعرض Roads API حد السرعة المنشور لجزء معيّن من الطريق. في حالة أجزاء الطريق ذات حدود السرعة المتغيرة، يتم عرض حد السرعة الافتراضي لهذا الجزء.
لا يمكن ضمان دقة بيانات حد السرعة التي تعرضها ميزة Roads API. بيانات حد السرعة المُقدَّمة ليست في الوقت الفعلي، وقد تكون مقدّرة أو غير دقيقة أو غير كاملة و/أو قديمة. يمكنك الاطّلاع على تفاصيل التغطية للاطّلاع على المناطق التي تتوفّر فيها بيانات حدّ السرعة.
طلبات
يجب إرسال طلب الحدّ الأقصى للسرعة عبر 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، ويمكن لأي منهما عرض أرقام تعريف أماكن متعددة من استدعاء واحد.