حدود السرعة

تعرض السمة 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 الحدّ الأقصى للسرعة المحدّدة للسيارات فقط.