حدود السرعة

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