حدود السرعة

تعرض Roads API حد السرعة المنشور لجزء معين من الطريق. في حالة قطاعات الطرق ذات حدود السرعة المتغيرة، يتم إرجاع حد السرعة الافتراضي للجزء.

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

الكائن Requests

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