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

القياسات

إرسال رحلات مجهولة لتحسين حركة المرور، وقراءة بيانات حركة المرور المجمَّعة.

القياسات

ساهِم برحلات GPS مجهولة يطابقها Navvo مع الطرق ويجمِّعها في طبقات حركة المرور الحية/الاعتيادية، واقرأ بيانات حركة المرور المجمَّعة. إذا كان لتطبيقك تدفق مواقع خاص به (سائقو توصيل، نقل ركاب، أساطيل)، فإن إرساله هنا يجعل حركة المرور أفضل للجميع — بما في ذلك أوقات الوصول المقدَّرة الخاصة بك.

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

الوحدات والإحداثيات. نقاط إدخال الرحلة تستخدم حقولًا مُسمّاة { lat, lng }؛ وspeed بوحدة الأمتار في الثانية؛ وcapturedAt طابع زمني بصيغة ISO-8601. جميع سرعات الخرج لحركة المرور بوحدة كم/س، وهندسة الخرج بصيغة GeoJSON على هيئة [lng, lat].

POST /telemetry/trips

إرسال رحلة. تُخزَّن الرحلة وتُدرَج في طابور لمطابقتها مع الطرق بشكل غير متزامن (عبر محرّك التوجيه الخاص بـ Navvo)؛ ويعود الطلب فورًا.

جسم الطلب

points
array required
نقاط GPS مرتَّبة (انظر بنية النقطة أدناه). يجب ألّا تكون فارغة.
userId
string
معرِّف UUID اختياري يميِّز المساهم. إن وُجد، فيجب أن يكون UUID صالحًا.
metadata
object
حر الصيغة. اضبط metadata.consentCaptured = false لوسم رحلة بأنها مفتقدة للموافقة (تُقبل رغم ذلك لكنها تُحتسب في ملخص الصحة). تُفترض الموافقة true فيما عدا ذلك.

كل عنصر في points[]:

الحقلالنوعمطلوبملاحظات
latnumberنعمخط العرض.
lngnumberنعمخط الطول.
speednumberلامتر/ثانية.
headingnumberلادرجات.
capturedAtstringلابصيغة ISO-8601؛ القيمة الافتراضية هي الوقت الحالي.
{
  "userId": "8b1f5c2e-3d4a-4e2b-9f10-7c2a1b6d9e44",
  "metadata": { "consentCaptured": true, "device": "ios-17" },
  "points": [
    { "lat": 31.9500, "lng": 35.9100, "speed": 12.1, "heading": 90, "capturedAt": "2026-05-16T12:00:00Z" },
    { "lat": 31.9512, "lng": 35.9123, "speed": 13.4, "heading": 88, "capturedAt": "2026-05-16T12:00:05Z" }
  ]
}

الاستجابة (201)

{ "accepted": true, "tripId": "f0a1c3d5-…", "jobId": "12" }

تُعالَج الرحلة في الخلفية: تُطابق مع شبكة الطرق، ثم تغذِّي السرعات المرصودة لكل حافة ملفات تعريف سرعة حركة المرور التي تُشغِّل نقاط نهاية حركة المرور. تصبح status بقيمة matched أو failed.

الخصوصية. أرسِل فقط البيانات التي لديك موافقة على مشاركتها، ويُفضَّل إخفاء هوية أطراف الرحلة (احذف أول/آخر بضع نقاط). الرحلات تُغذّي حركة المرور المجمَّعة فقط — ولا تُكشَف كمسارات فردية عبر الواجهة البرمجية.

GET /telemetry/trips

سرد أحدث 50 رحلة (دون ترقيم صفحات). كل عنصر هو رحلة تحمل status، وconsentCaptured، وrouteSummary (عدد النقاط/الحواف وأول/آخر نقطة)؛ ولا تُضمَّن النقاط الخام.

GET /telemetry/health

ملخص جودة الاستيعاب على أحدث 500 رحلة.

{
  "totalTrips": 500,
  "matchedTrips": 472,
  "failedTrips": 18,
  "consentMissingTrips": 3,
  "sampleRate": 0.944,
  "generatedAt": "2026-06-09T10:15:00.000Z"
}

GET /telemetry/daily

عدد الرحلات لكل يوم بتوقيت UTC على أحدث 365 رحلة.

[ { "day": "2026-06-09", "trips": 14 }, { "day": "2026-06-08", "trips": 31 } ]

GET /telemetry/traffic-overlay

طبقة حركة المرور المجمَّعة على هيئة FeatureCollection بصيغة GeoJSON من ملفات تعريف سرعة حواف الطرق مع تصنيف الازدحام — مصدر البيانات وراء طبقة حركة المرور على الخريطة.

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

mode
string
current (افتراضي؛ آخر ~6 ساعات تقريبًا) أو typical (متوسطات كل حافة على مدى الزمن كله).
bbox
string
مرشِّح مكاني west,south,east,north.
limit
string
الحدّ الأقصى للعناصر (محدود بمستوى التكبير؛ حتى 5000).
zoom
string
يحدِّد الحدّ الأقصى وتعميم الخطوط.
{
  "type": "FeatureCollection",
  "hasData": true,
  "mode": "current",
  "features": [
    {
      "type": "Feature",
      "geometry": { "type": "LineString", "coordinates": [[35.911, 31.951], [35.914, 31.952]] },
      "properties": { "edgeId": "e:128374", "congestion": "moderate", "averageSpeedKph": 28.4, "freeFlowSpeedKph": 55, "sampleCount": 4 }
    }
  ],
  "metadata": { "layerType": "traffic", "source": "navvo-telemetry-speed-profiles", "legend": { "light": { "color": "#188038" }, "moderate": { "color": "#D9A441" }, "heavy": { "color": "#D94B4B" }, "blocked": { "color": "#8B1A1A" } } }
}

congestion ∈ light | moderate | heavy | blocked | unknown.

الوصول المُبلَّط

للتحميل المحدود، تتوفر الطبقة أيضًا بعنونة بالبلاطات:

نقطة النهايةتُعيد
GET /telemetry/traffic-overlay/tile-coverقائمة بروابط البلاطات التي تغطي نطاق bbox (mode، bbox، zoom، maxTiles).
GET /telemetry/traffic-overlay/tiles/{z}/{x}/{y}الطبقة لبلاطة واحدة، على هيئة GeoJSON.
GET /telemetry/traffic-overlay/vector/{z}/{x}/{y}الطبقة لبلاطة واحدة، على هيئة بلاطة متجهية ثنائية (application/x-protobuf، الطبقة navvo_traffic).
استخدم المسار .../vector/{z}/{x}/{y} لإضافة حركة المرور كمصدر متجهي أصلي في Navvo Maps؛ واستخدم مسار بلاطة GeoJSON إن كنت تفضّل تنسيق العناصر بنفسك.

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

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

بلاطات الخريطة والأنماط

أنماط Navvo Maps، البلاطات المتجهية والنقطية، المحارف، والصور المركَّبة — خريطة أساس متكاملة من المصدر الأول.

Copyright © 2026