حدود السرعة

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