حدود السرعة

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