ذكاء المرور والملاحظات

يتعلّم Navvo أنماط المرور المعتادة من بيانات مجهولة المصدر مدفوعة بالطلب، ويوفّرها كـ ملفات واعية بالتقويم (رمضان / عطلة / نهاية أسبوع / معتاد)، وتصنيفات ازدحام مفهومة، وإرشاد وقت المغادرة، ورؤى للمنطقة، وخريطة شعبية آمنة للخصوصية. كما يوفّر تحليلات التغيير والحداثة ومدخلاً للملاحظات.

النطاق المطلوب: tiles (نموذج المرور)، insights (رؤى Navvo)، places (الملاحظات).

GET /traffic/profile

الازدحام المعتاد الواعي بالتقويم لمقطع طريق واحد، مع تدرّج: ramadan → holiday → weekend → typical. المعاملات: segmentKey (مطلوب)، at (اختياري)، country (افتراضي JO).

GET /traffic/labels

تصنيفات ازدحام من 4 فئات (Heavy / High / Normal / Low) لكل المقاطع داخل إطار bbox مع سبب نصي. ?bbox=minLng,minLat,maxLng,maxLat

GET /traffic/forecast

ازدحام تنبّؤي لمقطع واحد عند الآن + كل أفق زمني — «كيف سيبدو هذا الطريق بعد 15/30/60 دقيقة؟». تأتي التنبؤات من الملف النموذجي الواعي بالتقويم (يراعي العطل ورمضان ونهاية الأسبوع).

curl -s "https://navvo.io/api/v1/traffic/forecast?segmentKey=e:736821794312&horizons=0,30,60" \
  -H "x-api-key: $NAVVO_API_KEY"

{
  "provider": "navvo-traffic-model", "segmentKey": "e:736821794312", "model": "knn-profile",
  "forecast": [
    { "horizonMin": 0,  "at": "2026-07-09T08:00:00.000Z", "congestion": "moderate", "label": "High",
      "speedRatio": 0.47, "profileType": "typical", "sampleCount": 18 },
    { "horizonMin": 30, "at": "2026-07-09T08:30:00.000Z", "congestion": "light", "label": "Normal",
      "speedRatio": 0.71, "profileType": "typical", "sampleCount": 12 }
  ]
}

الأفق الذي لا ملف متعلَّماً له يعيد congestion: "unknown" مع label/speedRatio بقيمة null وsampleCount: 0 — عامله على أنه «لا تنبؤ»، لا انسياباً حراً.

GET /traffic/depart-optimizer

"غادر في الوقت المناسب" — أفضل ساعة مغادرة أقل ازدحاماً ضمن نافذة زمنية. ?bbox=...&from=6&to=22

POST /commute/advice

مستشار التنقّل الاستباقي — "متى ينبغي أن أغادر؟". يحدِّد مسار المنزل→العمل لزمن الوصول في انسياب حر، ثم يطبّق نموذج المرور التاريخي على الممر للحصول على زمن وصول معدَّل بالمرور، و(عند تحديد وقت وصول مستهدف) يعمل عكسياً لحساب وقت المغادرة المطلوب وحالة leave_now / leave_soon / on_track. استعلِم عنه لتنقّل محفوظ لرفع تنبيه استباقي. النطاق routing.

curl -s -X POST "https://navvo.io/api/v1/commute/advice" \
  -H "x-api-key: $NAVVO_API_KEY" -H "content-type: application/json" \
  -d '{ "home": {"lat":31.99,"lng":35.87}, "work": {"lat":31.95,"lng":35.93}, "arriveBy": "08:45" }'

{
  "provider": "navvo-commute", "available": true, "distanceKm": 9.6,
  "freeFlowEtaMin": 12, "trafficEtaMin": 16, "delayMin": 4,
  "congestion": "moderate", "basedOnHistory": true, "segmentsSampled": 23,
  "arriveBy": "08:45", "recommendedDepart": "08:24", "leaveInMin": 9,
  "status": "leave_soon", "message": "Leave in 9 min to arrive by 08:45.",
  "bestDepartureWindow": { "recommendedDeparture": "12:00", "worstDeparture": "17:00" }
}

يضرب trafficEtaMin زمن الانسياب الحر بازدحام الممر النمطي (بحدّ أقصى 2.5×)؛ وعند غياب تاريخ يغطّي الممر تكون basedOnHistory بقيمة false ويُستخدم زمن الانسياب الحر. ويحمل bestDepartureWindow نتيجة /traffic/depart-optimizer للسياق.

GET /traffic/dna

بصمة ازدحام لمنطقة/مسار يومي: منحنى 24 ساعة، ذروة صباحية/مسائية، فرق نهاية الأسبوع، ووصف نمطي.

GET /traffic/insights

تحليلات لمخططي المدن: أكثر المقاطع ازدحاماً، منحنى ساعات اليوم، مقارنة أيام الأسبوع بنهاية الأسبوع.

GET /traffic/popularity

خريطة نشاط آمنة للخصوصية — أعداد مُجمَّعة على شبكة خشنة وصادرة عبر الخصوصية التفاضلية. ?bbox=...&z=11

GET /insights/summary · النطاق insights

رؤى Navvo — تحليلات التغيير والحداثة على سجل التعديلات: التغييرات حسب النوع/الإجراء/اليوم، وحداثة كل مجموعة بيانات.

POST /feedback · النطاق places

إرسال ملاحظة داخل السياق (شريحة الملاحة، الصوت، المهام، النسخة التجريبية) مع حمولة سياق تلقائية.

{ "source": "nav_chip", "category": "road_closed", "severity": 4, "lat": 31.95, "lng": 35.91 }

POST /feedback/implicit · النطاق places

تسجيل إشارة سلوكية تُلمّح إلى مشكلة في الخريطة/الطريق — تبعثها حلقة الملاحة تلقائياً (دون كتابة من المستخدم). منفردةً تكون ضجيجاً؛ ومتجمّعةً تكشف مشاكل حقيقية (طريق مغلق، اتجاه واحد خاطئ، قيد انعطاف مفقود) دون أن يقدّم أحد بلاغاً.

curl -X POST "https://navvo.io/api/v1/feedback/implicit" \
  -H "content-type: application/json" \
  -d '{ "signal": "reroute", "lat": 31.9500, "lng": 35.9100 }'

→ { "ok": true, "signal": "reroute" }. الإشارة غير المعروفة تُعيد { "ok": false, "error": "unknown signal", "signals": [ … ] }.

GET /admin/feedback/problem-spots

نقاط مشاكل جغرافية مرتّبة — تُجمّع كل الملاحظات المفتوحة (الصريحة والضمنية) في خلايا ~110م وتُسجِّل كلّاً بـ الخطورة × ثقة المصدر × الحداثة. تَرجح البلاغات المتعمَّدة على الإشارات السلبية؛ والمهام بالكاد تُحتسب. تُظهر كل نقطة سبباً مهيمناً لطبقة خريطة تشغيلية. للمشرفين فقط (Bearer JWT، admin/super_admin).

?bbox=minLng,minLat,maxLng,maxLat&limit=100

{ "provider": "navvo-feedback", "scanned": 5, "spots": [
  { "lat": 31.9500, "lng": 35.9100, "count": 5, "score": 8.35,
    "dominantCategory": "implicit:reroute", "reason": "Frequent reroutes here",
    "signals": { "implicit:reroute": 3, "implicit:dead_end": 1, "road_closed": 1 },
    "sources": ["implicit", "nav_chip"], "lastAt": "2026-06-27T11:00:00.000Z" }
]}

GET /admin/feedback/routing-avoidances

عرض إغلاق الحلقة: البلاغات المعرقِلة التي أكّدها محرّر (status: ack) والتي توجّه المسارات الآن. عند تأكيد بلاغ يصبح تجنُّباً حيّاً في التوجيه (ضمن ~30م من أي ممر يمرّ به)؛ وتعليمه fixed/unactionable — أو مرور 60 يوماً — يزيله. يستشير محرك التوجيه هذه تلقائياً (avoidReported، مُفعّل افتراضياً) ويُبلّغ عن المطابقات في كتلة reportedConstraints. للمشرفين فقط.

{ "provider": "navvo-feedback", "count": 1, "ttlDays": 60, "avoidances": [
  { "id": "…", "category": "road_closed", "lat": 31.95, "lng": 35.91, "source": "nav_chip", "since": "2026-06-26T08:00:00.000Z" }
]}