حدود السرعة

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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