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