حركة المرور والحوادث
حركة المرور والحوادث
ازدحام لحظي واعتيادي مستمد بالكامل من شبكة الاستشعار المجهولة الخاصة بـ Navvo (لا يوجد أي تغذية لحركة المرور من طرف خارجي)، إضافة إلى حوادث الطرق المجمَّعة من المستخدمين.
النطاق المطلوب: traffic (التوجيه المراعي لحركة المرور POST /traffic/route يحتاج إلى كلا النطاقين routing وtraffic).
[lng, lat]. معامل bbox هو west,south,east,north. "بلاطات" خطوط الازدحام تُعيد GeoJSON، وليس بلاطات متجهية ثنائية. مفردات الازدحام: level ∈ free | slow | heavy | standstill؛ congestion ∈ light | moderate | heavy | blocked.GET /traffic/layers
واصف الطبقة وأسطورة الدليل للطبقة الحية لحركة المرور.
{
"layerType": "traffic",
"name": "Live traffic",
"source": "navvo-user-traffic",
"tilePattern": "/api/v1/traffic/lines/tiles/{z}/{x}/{y}",
"refreshSeconds": 60,
"legend": {
"free": { "label": "Free flow", "color": "#2dbe60" },
"slow": { "label": "Slow", "color": "#f9a825" },
"heavy": { "label": "Heavy", "color": "#e84b36" },
"standstill": { "label": "Standstill", "color": "#a01a12" }
}
}
GET /traffic/summary
تجميع للأحوال الحية ضمن نطاق bbox (أو عالميًا إذا حُذف bbox).
معاملات الاستعلام
west,south,east,north. احذفه لتلخيص جميع الحواف الحالية.{
"source": "navvo-user-traffic",
"bbox": "35.85,31.90,35.99,31.99",
"conditions": {
"hasData": true,
"sampledSegments": 128,
"congestionScore": 0.42,
"level": "slow",
"congestion": "moderate",
"summary": "Slow moving",
"breakdown": [
{ "level": "free", "segments": 60, "share": 46.9 },
{ "level": "slow", "segments": 40, "share": 31.2 }
]
},
"freshnessAt": "2026-06-09T08:55:00.000Z",
"freshnessLabel": "From Navvo users"
}
congestionScore هو متوسط مرجَّح بين 0 و1.
مزيج المرور النموذجي (البداية الباردة)
عندما لا تغطي أي مجسّات حية العرض الحالي، لا يعود الملخص فارغاً: بل يجيب من الملف النموذجي المتعلَّم لدى Navvo للساعة الحالية. الاستجابة موسومة بوضوح — ولا تُقدَّم أبداً على أنها حية:
{
"source": "navvo-typical-traffic",
"bbox": "35.85,31.90,35.99,32.02",
"conditions": {
"hasData": true, "sampledSegments": 0, "typical": true,
"level": "free", "congestion": "light",
"summary": "Typically free flowing now", "congestionScore": 0.11,
"breakdown": [ … ]
},
"freshnessAt": null,
"freshnessLabel": "Typical for this hour (no live reports yet)"
}
بدّل السلوك حسب source: تعني navvo-user-traffic بيانات مجسّات حية (freshnessLabel: "From Navvo users")؛ وتعني navvo-typical-traffic تقديراً تاريخياً — اعرضه مع freshnessLabel (مثلاً «نموذجي لهذه الساعة»)، لا كقراءة حية. وعندما لا توجد تغطية حية ولا نموذجية، يكون hasData بقيمة false وlevel بقيمة null مع freshnessLabel: "Awaiting Navvo user traffic".
GET /traffic/lines/tiles/{z}/{x}/{y}
خطوط الازدحام الحية لبلاطة واحدة، على هيئة GeoJSON FeatureCollection (تقتصر على الحواف المرصودة خلال آخر ~6 ساعات تقريبًا).
curl -s "https://navvo.io/api/v1/traffic/lines/tiles/14/9783/6592" -H "x-api-key: nvvo_YOUR_KEY"
{
"type": "FeatureCollection",
"hasData": true,
"features": [
{
"type": "Feature",
"properties": { "level": "slow", "congestion": "moderate", "color": "#f9a825", "edgeId": "edge-12345", "averageSpeedKph": 22.4, "freeFlowSpeedKph": 50 },
"geometry": { "type": "LineString", "coordinates": [[35.9106, 31.9539], [35.9121, 31.9558]] }
}
]
}
GET /traffic/lines/tile-cover
حساب البلاطات التي تغطي نطاق bbox لطبقة الخطوط الحية، مع روابط جاهزة.
معاملات الاستعلام
west,south,east,north.14.24.{
"layerType": "traffic", "zoom": 14, "capped": false,
"tilePattern": "/api/v1/traffic/lines/tiles/{z}/{x}/{y}",
"tiles": [ { "z": 14, "x": 9783, "y": 6592, "url": "/api/v1/traffic/lines/tiles/14/9783/6592" } ]
}
GET /traffic/predicted/tiles/{z}/{x}/{y}
الازدحام الاعتيادي/المتوقَّع لبلاطة واحدة (متوسطات تاريخية مرجَّحة بعدد العينات)، على هيئة GeoJSON. بنية مطابقة لبلاطة البيانات الحية، لكن properties لكل عنصر تحمل "predicted": true. وهناك مرافق GET /traffic/predicted/tile-cover يعمل مثل tile-cover الخاص بالبيانات الحية، ويقبل إضافةً إلى ذلك طابعًا زمنيًا at بصيغة ISO (يُدمج في الروابط المُعادة).
POST /traffic/route
حساب مسار وإثراء وقت وصوله المقدَّر ببيانات حركة مرور حية مصدرها Navvo. هذا هو النظير المراعي لحركة المرور لـ POST /routing/route: يحدِّد المسار عبر محرّك التوجيه الخاص بـ Navvo، ويأخذ عينات من الازدحام على امتداد المسار، ويُعيد وقت وصول معدَّلًا حسب حركة المرور إضافةً إلى تقسيم المسار إلى مقاطع ملوَّنة.
النطاقات المطلوبة: routing و traffic.
جسم الطلب
{ "lon": number, "lat": number, "name"?: string }. مطلوب 2 على الأقل.auto (افتراضي)، أو truck، أو bicycle، أو pedestrian، أو motor_scooter.arrivalTime. القيمة الافتراضية هي الوقت الحالي.en-US.[lon, lat]. عند توفيرها، تُؤخذ عينات الازدحام على طول هذا الشكل بالضبط ولا تتم إعادة تخطيط المسار — ما يضمن تطابق segments الملوّنة مع الخط الذي ترسمه (إعادة التخطيط قد تنتج مسارًا مختلفًا عن البديل الذي اختاره المستخدم). تُقبل حتى 10,000 نقطة (يُعاد أخذ العينات داخليًا إلى ≤ 2,000).shape — تُستخدم أساسًا لحساب durationInTrafficSeconds. لا معنى لها إلا مع shape؛ وبدونها تكون حقول الوقت المعدّل صفرًا وتبقى segments الملوّنة هي المفيدة.{
"locations": [ { "lon": 35.91, "lat": 31.95 }, { "lon": 35.95, "lat": 31.99 } ],
"costing": "auto",
"departureTime": "2026-06-09T08:30:00.000Z"
}
مع هندسة المسار المعروض لديك (يُنصح به عندما ترسم المسار بنفسك):
{
"locations": [ { "lon": 35.91, "lat": 31.95 }, { "lon": 35.95, "lat": 31.99 } ],
"shape": [ [35.91, 31.95], [35.917, 31.958], [35.93, 31.972], [35.95, 31.99] ],
"baseSeconds": 540,
"costing": "auto"
}
الاستجابة (201)
{
"provider": "navvo-user-traffic-routing",
"available": true,
"distanceKm": 6.42,
"baseDurationSeconds": 540,
"durationInTrafficSeconds": 637,
"delaySeconds": 97,
"departureTime": "2026-06-09T08:30:00.000Z",
"arrivalTime": "2026-06-09T08:40:37.000Z",
"traffic": {
"hasData": true,
"congestionScore": 0.33,
"level": "slow",
"trafficFactor": 1.18,
"congestedShare": 50
},
"segments": {
"type": "FeatureCollection",
"features": [
{ "type": "Feature", "properties": { "level": "free", "color": "#1A73E8" }, "geometry": { "type": "LineString", "coordinates": [[35.91, 31.95], [35.92, 31.96]] } },
{ "type": "Feature", "properties": { "level": "slow", "color": "#F9A825" }, "geometry": { "type": "LineString", "coordinates": [[35.92, 31.96], [35.95, 31.99]] } }
]
},
"legend": { "free": { "label": "Free", "color": "#1A73E8" }, "slow": { "label": "Slow", "color": "#F9A825" } }
}
| الحقل | الوصف |
|---|---|
baseDurationSeconds | وقت الوصول المقدَّر من محرّك التوجيه الخاص بـ Navvo، دون حركة مرور. |
durationInTrafficSeconds | وقت الوصول المقدَّر معدَّلًا حسب حركة المرور (base × trafficFactor). |
delaySeconds | الوقت الإضافي الناتج عن حركة المرور. |
traffic.trafficFactor | المُضاعِف المطبَّق على المدة الأساسية. |
segments | المسار على هيئة GeoJSON FeatureCollection، ملوَّن حسب الازدحام — اعرضه مباشرةً على الخريطة. |
إذا كان محرّك التوجيه متوقفًا، يكون available بقيمة false، والمُدد تساوي 0، وتكون segments فارغة.
الحوادث
حوادث الطرق المجمَّعة من المستخدمين — اختناقات، إغلاقات، حوادث سير، مخاطر، وغيرها. النطاق المطلوب: traffic.
type ∈ jam, closure, accident, hazard, weather, breakdown, speed_check, construction, lane_closure, visibility. والخطورة severity بين 1 و5. تُعاد فقط الحوادث active غير المنتهية الصلاحية.GET /incidents/types
كتالوج أنواع الحوادث المدعومة — لبناء قائمة اختيار "إبلاغ عن حادث". يحمل كل عنصر تسمية بشرية وخطورة افتراضية والعمر الافتراضي (defaultTtlMinutes) وما إذا كان النوع يحجب التوجيه (الأنواع الحاجبة تُلتَفّ حولها؛ والأنواع اللينة تنبّه السائق فقط).
curl -s "https://navvo.io/api/v1/incidents/types" -H "x-api-key: $NAVVO_API_KEY"
{
"provider": "navvo-incidents", "count": 10, "confirmBumpMinutes": 25, "maxTtlMinutes": 720,
"types": [
{ "type": "jam", "label": "Traffic jam", "defaultSeverity": 2, "defaultTtlMinutes": 90, "routeBlocking": false },
{ "type": "closure", "label": "Road closure", "defaultSeverity": 4, "defaultTtlMinutes": 240, "routeBlocking": true },
{ "type": "accident", "label": "Accident", "defaultSeverity": 4, "defaultTtlMinutes": 120, "routeBlocking": true }
]
}
قيم type هي بالضبط ما تقبله POST /incidents وPOST /incidents/report؛ ويصف confirmBumpMinutes/maxTtlMinutes كيف تُمدِّد التأكيداتُ عمرَ الحادث.
GET /incidents
سرد الحوادث النشطة، مرتَّبة حسب الخطورة ثم حسب الأحدث، مع بيانات وصفية للطبقة.
معاملات الاستعلام
west,south,east,north.{
"total": 1,
"items": [
{
"id": "b1f2c3d4-…",
"type": "accident",
"status": "active",
"location": "POINT(35.9106 31.9539)",
"title": "Two-car collision",
"severity": 4,
"expiresAt": "2026-06-09T10:40:00.000Z",
"confirmations": 3,
"rejections": 0
}
],
"metadata": { "layerType": "incidents", "source": "navvo-incidents", "dataUrl": "/api/v1/incidents/geojson", "hasData": true }
}
items[].location هو سلسلة نصية بصيغة WKT؛ وللحصول على إحداثيات مُحلَّلة استخدم نقطة نهاية GeoJSON أدناه.
GET /incidents/geojson
الحوادث النشطة على هيئة FeatureCollection بصيغة GeoJSON (الإحداثيات [lng, lat]). يقبل المرشِّحات نفسها bbox/type/limit/zoom. يتوفر أيضًا متغيِّر لكل بلاطة GET /incidents/geojson/tiles/{z}/{x}/{y} ومخطِّط تغطية GET /incidents/geojson/tile-cover.
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": { "type": "Point", "coordinates": [35.9106, 31.9539] },
"properties": { "id": "b1f2c3d4-…", "type": "accident", "title": "Two-car collision", "severity": 4, "confirmations": 3, "rejections": 0 }
}
],
"metadata": { "layerType": "incidents", "hasData": true }
}
POST /incidents
الإبلاغ عن حادث جديد.
جسم الطلب
1–5. القيمة الافتراضية 2.5–1440. القيمة الافتراضية 180.{ "type": "hazard", "lat": 31.9539, "lng": 35.9106, "title": "Debris on road", "severity": 3, "ttlMinutes": 120 }
تُعيد 201 مع الحادث المُنشأ (status: "active"، وexpiresAt محسوبة من ttlMinutes).
POST /incidents/report
مساعد البلاغ الجماعي — مثل POST /incidents لكن مع إزالة تلقائية للتكرار. إذا وُجد حادث نشط من النوع نفسه ضمن ~80م، يُعامَل هذا كـ تأكيد (يرفع confirmations للحادث ويجدّد صلاحيته) بدل إنشاء دبّوس مكرّر — وهو السلوك الصحيح عندما يبلّغ سائقون كثيرون عن الازدحام أو الحادث نفسه. وإلا يُنشأ حادث جديد.
نفس جسم POST /incidents، مضافاً إليه dedupMeters اختياري (افتراضي 80، أقصى 500).
curl -s -X POST "https://navvo.io/api/v1/incidents/report" \
-H "x-api-key: $NAVVO_API_KEY" -H "content-type: application/json" \
-d '{ "type": "jam", "lat": 31.97, "lng": 35.92, "severity": 3, "title": "Heavy traffic" }'
{ "provider": "navvo-incidents", "merged": true, "distanceM": 31, "confirmations": 2, "incident": { } }
| الحقل | النوع | ملاحظات |
|---|---|---|
merged | boolean | true إذا دُمج في حادث قريب من النوع نفسه (تأكيد)؛ وfalse إذا أُنشئ جديد |
distanceM | number | (عند الدمج) المسافة إلى الحادث المُطابَق |
confirmations | number | (عند الدمج) عدد تأكيدات الحادث بعد هذا البلاغ |
incident | object | الحادث الناتج |
استخدمه من زرّ "إبلاغ" كي تتجمّع البلاغات المتكرّرة لحدث واحد في دبّوس واحد متزايد التأكيد بدل ازدحام الخريطة.
POST /incidents/{id}/votes
تأكيد حادث أو رفضه (تحقق جماعي). تُعيد 201 مع الحادث المُحدَّث. الحادث الذي يحصل على 5 رفضات فأكثر (وعدد الرفضات يفوق ضعف التأكيدات) يُوسَم تلقائيًا بـ rejected ويسقط من القوائم.
جسم الطلب
confirm أو reject.{ "vote": "confirm" }
تعديلات الطرق والإغلاقات
تعديلات الطرق يتم إنشاؤها على منصة Navvo (لوحة العمليات) وهي النظير الرسمي الأطول
عمراً للحوادث الجماعية: إغلاقات الطرق، قيود الوصول، طرق مرسومة مخصّصة،
وتعديلات السمات. التعديلات الفعّالة تظهر على الخريطة وفي هذه الواجهة البرمجية،
وبالنسبة للإغلاقات/القيود تُلتَفّ حولها في التوجيه تلقائياً (انظر
roadEditConstraints في استجابة المسار). كل تعديل قد يكون
دائماً أو مؤقتاً (بنافذة بداية/نهاية).
النطاق المطلوب: tiles
GET /road-edits/geojson
تعديلات الطرق الفعّالة في منطقة العرض على هيئة FeatureCollection بصيغة GeoJSON
بهندسة مختلطة (LineString لمقاطع الطرق، Polygon لإغلاقات المناطق، Point للتعديلات
النقطية). تُعاد فقط التعديلات الفعّالة الآن (التعديل المجدول يظهر بعد مرور وقت بدايته،
والمنتهي أو المعطّل يسقط).
west,south,east,north. احذفها للحصول على الكل (بحد أقصى).curl -s "https://navvo.io/api/v1/road-edits/geojson?bbox=35.8,31.9,36.0,32.0" \
-H "x-api-key: $NAVVO_API_KEY"
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": { "type": "LineString", "coordinates": [[35.911, 31.954], [35.912, 31.955]] },
"properties": {
"id": "…", "layerType": "road_edits", "editType": "closure", "geometryType": "line",
"name": "Rainbow St closed", "reason": "construction", "status": "active",
"severity": 4, "blocksRouting": true,
"startsAt": null, "endsAt": "2026-07-01T18:00:00.000Z", "permanent": false,
"color": "#DC2626"
}
}
],
"metadata": { "layerType": "road_edits", "name": "Road edits", "source": "navvo-road-edits", "hasData": true }
}
| الخاصية | ملاحظات |
|---|---|
editType | closure · restriction · custom_road · attribute |
geometryType | line · polygon · point |
blocksRouting | عند true يلتفّ التوجيه حول هذا التعديل |
permanent / startsAt / endsAt | نافذة الصلاحية (permanent: true ⇐ بلا نهاية) |
color | لون العرض المقترَح لنوع التعديل |
custom_road هي تعليقات على الخريطة — تُرسَم لكنها غير قابلة للتوجيه (محرّك
التوجيه يسير على رسم بياني مُجهَّز مسبقاً؛ والطريق الجديد القابل للقيادة يحتاج إعادة بناء
الرسم البياني). أما الإغلاقات والقيود والتعديلات فتأخذ مفعولها فوراً.