حدود السرعة

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