حدود السرعة

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