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نعمخط العرض، −90..90.
lngnumberنعمخط الطول، −180..180.
speednumberلامتر/ثانية.
headingnumberلادرجات.
capturedAtstringلابصيغة ISO-8601؛ القيمة الافتراضية هي الوقت الحالي.
تُتحقَّق النقاط: يجب أن يكون lat/lng أرقامًا موجودة ضمن المدى، وspeed/heading رقميّين، وتحمل الرحلة 5000 نقطة كحدّ أقصى. النقاط الخارجة عن المدى أو المشوّهة تعيد 400 مع مصفوفة تحقّق.
{
  "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.

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

POST /telemetry/errors

الإبلاغ عن أعطال وأخطاء جهة العميل، بشكل مجمَّع. مصرف خفيف للإبلاغ عن الأعطال لتطبيقاتك المُشغَّلة بـ Navvo (الويب، أندرويد، iOS): أرسِل الاستثناءات المُلتقَطة أو الأعطال القاتلة وتخزّنها Navvo للفرز.

المصادقة غير مطلوبة — يجب ألّا يُحجَب مُبلِّغ الأعطال أبدًا. إذا أرسلت Authorization: Bearer <token> صالحًا، فيُنسَب البلاغ إلى ذلك المستخدم المُوثَّق؛ وإلا فيكون مجهولًا. ولا يُوثَق أبدًا بمعرِّف مستخدم مُقدَّم من العميل. هذا المسار مقيَّد بمعدّل 30 طلبًا/دقيقة لكل عنوان IP.

جسم الطلب

errors
array required
حتى 20 عنصر خطأ (انظر البنية أدناه). يجب ألّا تكون فارغة.

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

الحقلالنوعمطلوبملاحظات
platformstringنعمweb أو android أو ios.
messagestringنعمرسالة الخطأ (بحدّ أقصى 2000 حرف).
stackstringلاأثر المكدّس (بحدّ أقصى 8000 حرف).
appVersionstringلاإصدار تطبيقك.
deviceModelstringلاطراز الجهاز.
osVersionstringلاإصدار نظام التشغيل.
contextobjectلاسياق منظَّم حرّ الصيغة (الشاشة، الحالة، فتات التتبّع).
occurredAtstringلاطابع زمني بصيغة ISO-8601؛ القيمة الافتراضية هي وقت الاستلام.
{
  "errors": [
    { "platform": "android", "appVersion": "3.2.1", "deviceModel": "Pixel 8",
      "osVersion": "Android 15", "message": "TypeError: cannot read property 'lat' of null",
      "stack": "at MapView.render (map.js:214)…", "context": { "screen": "navigation" },
      "occurredAt": "2026-07-19T09:20:00Z" }
  ]
}

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

{ "ok": true, "accepted": 1 }

accepted هو عدد صفوف الأخطاء المخزَّنة. العناصر المفتقدة لـ platform/message أو المتجاوزة لحدّ الطول تعيد 400 مع مصفوفة تحقّق. تُحتفَظ البلاغات المخزَّنة لفترة محدودة (30 يومًا افتراضيًا) ثم تُمسَح.

GET /telemetry/trips

للمشرفين فقط. تتطلّب هذه النقطة الآن مستخدم Navvo مُسجَّل الدخول بدور admin/super_admin (رمز JWT من نوع Bearer)؛ ويحصل المتصلون الآخرون على 403. كانت قابلة للقراءة سابقًا في الوضع بلا مفتاح وتكشف معرّفات المساهمين وأول/آخر نقاط GPS.

سرد أحدث الرحلات (دون ترقيم صفحات). كل عنصر هو رحلة تحمل 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