حدود السرعة

تعرض واجهة برمجة التطبيقات 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=ChIJs5ydyTiuEmsR0fRSlU0C7k0&placeId=ChIJW__r4ERXzpQRgkeRL6P0m3Y

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

ماذا لو كان جزء من الطريق يعرض حدود سرعة منفصلة للسيارات والشاحنات؟

تعرض السمة Roads API الحد الأقصى للسرعة المسموح بها للسيارات فقط.