حدود السرعة

تعرِض 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 دقيقة (تعتمد القيمة الدقيقة على السرعة التي تسير بها مادة العرض). إذا كانت مادة العرض ثابتة، يكفي نموذج موقع جغرافي واحد (ما مِن حاجة إلى إجراء مكالمات متعددة).

للحدّ من وقت الاستجابة الإجمالي، ننصحك بالاتصال بخدمة Speed Limit بعد تجميع بعض البيانات، بدلاً من الاتصال بواجهة برمجة التطبيقات في كل مرة يتم فيها تلقّي الموقع الجغرافي لمادة عرض للأجهزة الجوّالة.

لماذا لا تظهر بعض حدود السرعة أو كلها؟

إنّ السبب الأكثر شيوعًا لعدم توفّر speedLimits هو طلب الحد الأقصى للسرعة لمكان ليس جزءًا من طريق.

يستخدِم المثال أعلاه جسر فاسكو دا جاما لتوضيح المفاهيم، ويربط الجسر الطريق E90 التي تعبر نهر تيجو. يحمل الجسر رقم تعريف مكان هو ChIJUzt97ZEwGQ0RM1JzQfqoDtU. إنّ الجزء الأول من الطريق في الاستجابة أعلاه هو جزء من طريق E90 ويحمل رقم تعريف المكان ChIJX12duJAwGQ0Ra0d4Oi4jOGE. في مثال الطلب، إذا استبدلت معرّف مكان الطريق بمعرّف مكان الجسر، لن يتضمّن الردّ سوى حدود سرعتَين في صفيف speedLimits لأنّ معرّف مكان الجسر لا يشير إلى جزء فردي من الطريق. بالإضافة إلى ذلك، إذا لم يكن أي من أرقام تعريف المواقع الجغرافية خاصًا بمقاطع الطرق، لن يحتوي الردّ على أي حدود للسرعة.

عند تقديم طلبات حدود السرعة باستخدام معرّفات الأماكن، تأكّد من أنّ كل معرّف مكان يشير إلى جزء من الطريق وليس إلى نوع مختلف من الأماكن. إنّ أفضل طريقة لاسترداد أرقام تعريف الأماكن لمقاطع طرق فردية هي استخدام طلبات snapToRoads أو nearestRoads، إذ يمكن أن يعرض أيّ منهما أرقام تعريف أماكن متعددة من دعوة واحدة.