Navvo
مرجع الواجهة البرمجية

حركة المرور والحوادث

الازدحام الحي والاعتيادي، أوقات الوصول المراعية لحركة المرور، وحوادث الطرق المجمَّعة من المستخدمين.

حركة المرور والحوادث

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

النطاق المطلوب: traffic (التوجيه المراعي لحركة المرور POST /traffic/route يحتاج إلى كلا النطاقين routing وtraffic).

الإحداثيات بصيغة GeoJSON على هيئة [lng, lat]. معامل bbox هو west,south,east,north. "بلاطات" خطوط الازدحام تُعيد GeoJSON، وليس بلاطات متجهية ثنائية. مفردات الازدحام: levelfree | slow | heavy | standstill؛ congestionlight | 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).

معاملات الاستعلام

bbox
string
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 لطبقة الخطوط الحية، مع روابط جاهزة.

معاملات الاستعلام

bbox
string required
west,south,east,north.
zoom
number
مستوى تكبير البلاطة، محصور بين 12 و16. القيمة الافتراضية 14.
maxTiles
number
حدٌّ أقصى للبلاطات المُعادة، محصور بين 1 و48. القيمة الافتراضية 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.

جسم الطلب

locations
array required
مصفوفة من { "lon": number, "lat": number, "name"?: string }. مطلوب 2 على الأقل.
costing
string
auto (افتراضي)، أو truck، أو bicycle، أو pedestrian، أو motor_scooter.
departureTime
string
طابع زمني بصيغة ISO لوقت المغادرة؛ وهو الأساس لحساب arrivalTime. القيمة الافتراضية هي الوقت الحالي.
language
string
لغة السرد الإرشادي. القيمة الافتراضية en-US.
shape
array
اختياري: هندسة مسارٍ تعرضه بالفعل، كمصفوفة من أزواج [lon, lat]. عند توفيرها، تُؤخذ عينات الازدحام على طول هذا الشكل بالضبط ولا تتم إعادة تخطيط المسار — ما يضمن تطابق segments الملوّنة مع الخط الذي ترسمه (إعادة التخطيط قد تنتج مسارًا مختلفًا عن البديل الذي اختاره المستخدم). تُقبل حتى 10,000 نقطة (يُعاد أخذ العينات داخليًا إلى ≤ 2,000).
baseSeconds
number
اختياري: المدة بدون ازدحام (بالثواني) للشكل المُرسَل في 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.

نوع الحادث typejam, 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

سرد الحوادث النشطة، مرتَّبة حسب الخطورة ثم حسب الأحدث، مع بيانات وصفية للطبقة.

معاملات الاستعلام

bbox
string
مرشِّح مكاني west,south,east,north.
type
string
ترشيح حسب نوع الحادث.
limit
number
الحدّ الأقصى للعناصر، 1–250 (محدود أيضًا بمستوى التكبير).
zoom
string
يتحكم في الحدّ الأقصى الافتراضي.
{
  "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

الإبلاغ عن حادث جديد.

جسم الطلب

type
string required
أحد أنواع الحوادث المذكورة أعلاه.
lat
number required
خط العرض.
lng
number required
خط الطول.
title
string
عنوان قصير.
description
string
نص حر.
severity
number
15. القيمة الافتراضية 2.
ttlMinutes
number
مدة البقاء بالدقائق، 51440. القيمة الافتراضية 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": { } }
الحقلالنوعملاحظات
mergedbooleantrue إذا دُمج في حادث قريب من النوع نفسه (تأكيد)؛ وfalse إذا أُنشئ جديد
distanceMnumber(عند الدمج) المسافة إلى الحادث المُطابَق
confirmationsnumber(عند الدمج) عدد تأكيدات الحادث بعد هذا البلاغ
incidentobjectالحادث الناتج

استخدمه من زرّ "إبلاغ" كي تتجمّع البلاغات المتكرّرة لحدث واحد في دبّوس واحد متزايد التأكيد بدل ازدحام الخريطة.

POST /incidents/{id}/votes

تأكيد حادث أو رفضه (تحقق جماعي). تُعيد 201 مع الحادث المُحدَّث. الحادث الذي يحصل على 5 رفضات فأكثر (وعدد الرفضات يفوق ضعف التأكيدات) يُوسَم تلقائيًا بـ rejected ويسقط من القوائم.

جسم الطلب

vote
string required
confirm أو reject.
userId
string
معرِّف اختياري للمصوِّت.
{ "vote": "confirm" }

تعديلات الطرق والإغلاقات

تعديلات الطرق يتم إنشاؤها على منصة Navvo (لوحة العمليات) وهي النظير الرسمي الأطول عمراً للحوادث الجماعية: إغلاقات الطرق، قيود الوصول، طرق مرسومة مخصّصة، وتعديلات السمات. التعديلات الفعّالة تظهر على الخريطة وفي هذه الواجهة البرمجية، وبالنسبة للإغلاقات/القيود تُلتَفّ حولها في التوجيه تلقائياً (انظر roadEditConstraints في استجابة المسار). كل تعديل قد يكون دائماً أو مؤقتاً (بنافذة بداية/نهاية).

النطاق المطلوب: tiles

GET /road-edits/geojson

تعديلات الطرق الفعّالة في منطقة العرض على هيئة FeatureCollection بصيغة GeoJSON بهندسة مختلطة (LineString لمقاطع الطرق، Polygon لإغلاقات المناطق، Point للتعديلات النقطية). تُعاد فقط التعديلات الفعّالة الآن (التعديل المجدول يظهر بعد مرور وقت بدايته، والمنتهي أو المعطّل يسقط).

bbox
string
حدود منطقة العرض 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 }
}
الخاصيةملاحظات
editTypeclosure · restriction · custom_road · attribute
geometryTypeline · polygon · point
blocksRoutingعند true يلتفّ التوجيه حول هذا التعديل
permanent / startsAt / endsAtنافذة الصلاحية (permanent: true ⇐ بلا نهاية)
colorلون العرض المقترَح لنوع التعديل
تعديلات custom_road هي تعليقات على الخريطة — تُرسَم لكنها غير قابلة للتوجيه (محرّك التوجيه يسير على رسم بياني مُجهَّز مسبقاً؛ والطريق الجديد القابل للقيادة يحتاج إعادة بناء الرسم البياني). أما الإغلاقات والقيود والتعديلات فتأخذ مفعولها فوراً.
Copyright © 2026