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

صور الشوارع

صور على مستوى الشارع وميزات الطرق من شبكة صور Navvo.

صور الشوارع

صور على مستوى الشارع وميزات خرائط الطرق (الإشارات، الإشارات الضوئية، المعابر) لنقطة أو إطار إحاطة (bounding box) أو ممر مسار — مصدرها شبكة صور Navvo.

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

معامل bbox هنا هو minLng,minLat,maxLng,maxLat (غرب، جنوب، شرق، شمال). تكون إحداثيات الصور/الميزات بصيغة GeoJSON [lng, lat]. تحمل استجابات JSON بيانات وصفية للتخزين المؤقت (cacheStatus, cachedAt, refreshedAt) وsourceAttributionRequired: true — يكون إسناد صور Navvo إلزاميًا عند عرضك للصور. تُحدّ أطر الإحاطة المطلوبة وأعداد النتائج من جهة الخادم بناءً على zoom.

GET /imagery/mapillary

نقاط الصور على مستوى الشارع ضمن إطار إحاطة.

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

bbox

string required

minLng,minLat,maxLng,maxLat، مثال 35.9,31.9,35.95,31.96.

zoom

string

مستوى تكبير الخريطة — يتحكم في حد إطار الإحاطة وحد النتائج الافتراضي.

limit

string

الحد الأقصى للصور (محصور بين 1–200).

{
  "provider": "navvo",
  "configured": true,
  "available": true,
  "bbox": "35.922500,31.929500,35.932500,31.939500",
  "images": [
    {
      "id": "498763215480123",
      "thumb_256_url": "https://…/256.jpg",
      "computed_geometry": { "type": "Point", "coordinates": [35.9281, 31.9344] },
      "captured_at": 1700000000000,
      "sequence": "j1UNvFYGJqcMLi2Zay7l9n"
    }
  ],
  "cacheStatus": "fresh",
  "sourceAttributionRequired": true
}

عندما لا تكون شبكة الصور مهيّأة: configured:false, available:false, images:[].

GET /imagery/nearest-image

أقرب صورة على مستوى الشارع لنقطة، إضافة إلى الصور القريبة ورمز عميل (client token) لعارض صور Navvo.

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

lon

string required

خط الطول.

lat

string required

خط العرض.

{
  "available": true,
  "image": {
    "id": "498763215480123",
    "thumb_1024_url": "https://…/1024.jpg",
    "captured_at": "2023-11-14T22:13:20.000Z",
    "sequence_id": "j1UNvFYGJqcMLi2Zay7l9n",
    "computed_geometry": { "type": "Point", "coordinates": [35.9051, 31.9649] }
  },
  "nearby": [ /* up to 11 more, same shape */ ],
  "clientToken": "MLY|…",
  "sourceAttributionRequired": true
}

clientToken هو رمز عارض صور Navvo للاستخدام مع عارض صور Navvo من جهة العميل. يكون available:false عندما لا يكون هناك رمز مهيّأ أو لا توجد صور.

GET /imagery/sequence

جميع صور تسلسل صور Navvo بترتيب الالتقاط (لتشغيل عرض الشارع).

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

string required

معرّف تسلسل صور Navvo.

imageId

string

معرّف الصورة التي يبدأ منها التشغيل؛ تبدأ النافذة المُعادة هناك.

يُعيد ما يصل إلى 150 صورة لكل استدعاء: { sequenceId, count, fetched, orderedImageIds, images, … }.

GET /imagery/map-features

ميزات خرائط الطرق (الإشارات، الإشارات الضوئية، المعابر) ضمن إطار إحاطة، كقائمة موحّدة إضافة إلى FeatureCollection بصيغة GeoJSON. نفس معاملات bbox/zoom/limit كما في /imagery/mapillary.

تُوحَّد كل ميزة بـ category (واحدة من traffic_light, speed_limit, stop, yield, no_entry, turn_restriction, pedestrian_crossing, parking, other).

{
  "provider": "navvo",
  "available": true,
  "features": [ { "id": "112233", "object_value": "regulatory--stop--g1", "category": "stop", "geometry": { "type": "Point", "coordinates": [35.9277, 31.9602] } } ],
  "geojson": { "type": "FeatureCollection", "features": [ /* … camelCase properties … */ ] },
  "sourceAttributionRequired": true
}

POST /imagery/map-features/corridor

ميزات الخرائط على امتداد ممر مسار — بناء صندوق محشوّ حول خط متعدد (polyline) وإعادة الميزات الواقعة داخله.

جسم الطلب

coordinates

array

نقاط المسار كأزواج [lng, lat]. (قدّم هذا أوpolyline.)

polyline

string

بديل: "lng,lat;lng,lat;…".

widthMeters

string

عرض الممر، محصور بين 40–800. القيمة الافتراضية 180.

limit

string

الحد الأقصى للميزات (محدود بـ 200).

zoom

string

القيمة الافتراضية 15.

{ "coordinates": [[35.90, 31.95], [35.91, 31.96]], "widthMeters": "120" }

يُعيد 201 بنفس البنية الخاصة بـ /imagery/map-features، إضافة إلى كتلة corridor (bbox, widthMeters, points).

GET /imagery/mapillary-tiles/{z}/{x}/{y}

نقطة نهاية البلاطة المتجهة لتغطية الصور (MVT/protobuf) — حيث تتوفّر صور مستوى الشارع. الطبقات المصدرية: sequence (خط، خطوط التغطية، التكبير 6–14)، وimage (نقطة، الصور الفردية، التكبير 14)، وoverview (نقطة، نقاط منخفضة التكبير، 0–5). أقصى تكبير للمصدر 14 (تكبير زائد لما فوق 15). تُعيد بيانات ثنائية (application/x-protobuf) مع ترويسات x-navvo-*. تُعيد 503 إذا لم تكن الشبكة مهيّأة، و502 إذا كانت غير قابلة للوصول.

ارسم طبقة sequence كطبقة خط (line) لإظهار تغطية «street view متاح» (يستخدم Navvo الأخضر #05CB63).

GET /imagery/sign-tiles/{z}/{x}/{y}

نقطة نهاية البلاطة المتجهة لإشارات المرور (MVT/protobuf) — كل إشارة مرور مكتشفة كنقطة. الطبقة المصدرية traffic_sign (نقطة، متاحة عند التكبير 14، وأقصى تكبير للمصدر 14 مع تكبير زائد لما فوق 15). تحمل خاصية value نوع الإشارة بصيغة {category}--{name}--{group} (مثل regulatory--stop--g1، warning--curve-left--g1؛ الفئات: regulatory، warning، information، complementary). ارسمها كطبقة رموز (symbol) مع icon-image مُشتقّة من value لعرض أيقونات الإشارات الرسمية. نفس الاستجابة الثنائية وسلوك التخزين المؤقت و503/502 كبلاطات التغطية.

تضم تصنيفات الإشارات مئات المتغيّرات (نحو 10 من regulatory--stop--g1..g10، ونحو 90 من متغيرات maximum-speed-limit، وغيرها). لواجهة مناسبة للسائق، اجمعها في عدد قليل من الخيارات عبر مطابقة أجزاء من value — مثل كل --stop-- → «قف»، وكل speed-limit → «حدود السرعة»، وكل warning-- → «تحذيرات». رشّح طبقة الرموز بتعبير نمط مثل ["case", [">=", ["index-of", "--stop--", ["get", "value"]], 0], true, false].

GET /imagery/point-tiles/{z}/{x}/{y}

نقطة نهاية البلاطة المتجهة لنقاط الخريطة (MVT/protobuf) — النقاط والمعالم المكتشفة على الطريق (أعمدة الإنارة، كاميرات المراقبة، الأقماع، علامات الطريق، فتحات الصيانة، المقاعد، إلخ) كنقاط. الطبقة المصدرية point (نقطة، متاحة عند التكبير 14، وأقصى تكبير للمصدر 14 مع تكبير زائد لما فوق 15). تحمل خاصية value نوع المعلم بصيغة object--{name} أو marking--{name} أو construction--{name} (مثل object--street-light، object--cctv-camera، object--traffic-cone، marking--discrete--crosswalk-zebra). ارسمها كطبقة رموز (symbol) مع icon-image: ["get", "value"] بحيث يعرض كل معلم أيقونته الخاصة (ممر المشاة والسهم الأرضي يظهران بأيقونتين مختلفتين)، مع تقييدها بحدّ تكبير أعلى (نحو 15) للحفاظ على نظافة الخريطة. نفس الاستجابة الثنائية وسلوك التخزين المؤقت و503/502 كبلاطات التغطية.

كما هو الحال مع الإشارات، ارسم النقاط كطبقة رموز (symbol) (أيقونة لكل value) وليس كدوائر مصمتة. بعض قيم النقاط تحمل لاحقة اتجاه (object--traffic-light--general-upright-front / -side / -back)؛ إن أبقيت على أيقونة لكل قيمة، فارجع إلى الاسم الأساس بعد إزالة لاحقة الاتجاه (…--general-upright) عند غياب الأيقونة الدقيقة.

تصنيف النقاط كبير، لذا اجمعها حسب جزء من value (object--street-light → «أعمدة الإنارة»، marking-- → «علامات الطريق»، construction-- / object--traffic-cone → «أعمال وأقماع»، object--cctv-camera → «كاميرات المراقبة»). ولتحكّم أدق، اعرض خيارات فرعية لكل مجموعة (مثل علامات الطريق ← ممرات المشاة / أسهم المسارات / خطوط الأولوية / خطوط التوقف)، وابنِ مرشّح الطبقة من اتحاد مُطابِقات الخيارات الفرعية المحددة — وعند تحديد المجموعة كاملةً استخدم مُطابِقها الواسع لإظهار المتغيّرات التي لا خيار فرعي مخصص لها.

GET /imagery/kartaview

عنصر نائب اختياري لموصّل مصدر صور إضافي — يُعيد حاليًا { "configured": false, "images": [] }.

قاعدة بيانات الإشارات والنقاط (مصدرنا أولاً) — `/signs/*`

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

GET /signs/features

يُعيد الإشارات والنقاط المحفوظة ضمن مربّع إحاطة كـFeatureCollection بصيغة GeoJSON. عند أول زيارة لمنطقة تستورد Navvo البلاطات المغطّية ثم تخدم من قاعدتها.

المعامل	الوصف
`bbox`	`minLng,minLat,maxLng,maxLat` (مطلوب)
`kinds`	قائمة من `sign`,`point` (الافتراضي كلاهما)

كل معلم: الهندسة Point؛ والخصائص تحمل value (مثل regulatory--no-entry--g1) وkey ثابتًا وkind (sign|point) وsrc محايدًا (navvo|admin). ارسمها كطبقة رموز (symbol) مع icon-image: ["get","value"]. السجلات المخفية/المحذوفة لا تُعاد أبدًا.

لإظهار حدّ السرعة الحالي على عدّاد السرعة، اقرأ إشارات maximum-speed-limit-{n} من هذه النقطة، وأسقِطها على المسار النشط (المسافة التراكمية على طول الشكل)، واعرض آخر إشارة تجاوزها السائق — فتستمر حتى الإشارة التالية، وتبقى الإشارة الأخيرة حتى نهاية المسار. فشارع بحدود 60 ← 80 ← 100 يتدرّج عند تجاوز كل إشارة. خارج الملاحة، ارجع إلى أقرب إشارة سرعة.

POST /signs/report

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

تجاهلات المستخدم — `GET/POST/DELETE /me/sign-disregards` (مصادقة)

يمكن للراكب المسجّل تجاهل إشارة محددة: تُخفى من خريطته ويتجاهلها التوجيه له وحده (بيانات النظام لا تتغير). أرسل POST { key, value, lat, lng } للإضافة، وDELETE /me/sign-disregards/:idOrKey للاستعادة، وGET للعرض.

التوجيه يحترم الإشارات. يقبل POST /routing/plan حقلاً اختياريًا disregard: string[] (مفاتيح تجاهلات الراكب) ويعيد كتلة signConstraints ({ applied, noEntryCount, source: "navvo-signs" }). تتحوّل إشارات ممنوع الدخول/الحظر الواقعة ضمن ~28 مترًا من المسار المخطّط إلى استثناءات توجيه بحيث تخرج الطرق المحظورة من خيارات المسار (تحسب Navvo المسار أولاً ثم تطابق القيود مع الممر الفعلي — فإشارة ممنوع الدخول على شارع جانبي مواز لا يسلكه المسار لا تؤثر عليه) — باستثناء تجاهلات الراكب. وإن أدّى استثناؤها إلى عدم وجود مسار، تعيد Navvo المحاولة بدون القيود حتى لا يفشل التوجيه أبدًا.

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

إعداد الخريطة، أنماط الفئات، الطبقات العلوية، الطقس، وتقييم مخاطر المسار المراعي للأحوال.

عرض خريطة

ضمّن خريطة أساس تفاعلية من Navvo Maps في تطبيقك.