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

كل ما يُركَّب فوق خريطة الأساس: بيان إعداد الخريطة، أنماط علامات الفئات، صور الأيقونات المركَّبة، الطبقات العلوية المتجهية/بصيغة GeoJSON، الطقس، وتقييم مخاطر المسار الذي يدمج حركة المرور والطقس والحوادث ومناطق اللوجستيات وأصول الإنفاذ.

النطاق المطلوب: tiles للإعداد والطبقات العلوية والطقس؛ و**routing** لنقاط نهاية POST الخاصة بمخاطر المسار/الإنفاذ.

GET /map/config

بيان إعداد الخريطة الكامل من المصدر الأول: الأنماط الأساسية، الطبقات العلوية، الفئات، الأيقونات، الطقس، النمط ثلاثي الأبعاد، مناطق اللوجستيات، وكتلة capabilities التي تصف نقاط النهاية العامة وحدود الأداء. اجلب هذا مرة واحدة عند بدء التشغيل لاكتشاف ما هو متاح وكيفية تحميله.

المفاتيح من المستوى الأعلى: layers، baseStyles، overlays، categories، icons، iconSpriteUrl، iconSpriteManifestUrl، categoryStyleManifest، threeD، logisticsZones، capabilities.

{
  "baseStyles": [ { "key": "standard", "name": "Navvo", "kind": "base", "endpoint": "/api/v1/tiles/style?style=standard" } ],
  "overlays": [ { "key": "traffic", "kind": "overlay", "layerType": "traffic", "tileUrl": "/api/v1/traffic/lines/tiles/{z}/{x}/{y}" } ],
  "iconSpriteUrl": "/api/v1/map/icons/sprite.svg",
  "capabilities": {
    "publicEndpoints": { "config": "/api/v1/map/config", "routeRisk": "/api/v1/map/route-risk" },
    "performance": { "defaultTileCoverCap": 64, "maxTileCoverCap": 256, "tileAddressedOverlays": true },
    "vectorOverlays": { "enabled": true, "format": "mvt" }
  }
}

GET /map/layers

فهرس مسطَّح لجميع الطبقات المُعدَّة: { items, baseStyles, overlays, total, requiredOverlays }. يسرد requiredOverlays أنواع طبقات الطبقات العلوية التي يتوقعها Navvo (مثل traffic، transit، incidents، weather، logistics_zones).

GET /map/category-styles

تنسيق جاهز للعرض لفئات الأماكن — ألوان العلامات، أنماط الدبابيس، الأيقونات، الأسماء متعددة اللغات، والأسماء البديلة. استخدمه لرسم علامات ملوَّنة حسب الفئة تطابق خريطة Navvo نفسها.

{
  "version": 1,
  "iconSpriteUrl": "/api/v1/map/icons/sprite.svg",
  "categories": [
    {
      "slug": "restaurants",
      "name": { "en": "Restaurants", "ar": "مطاعم" },
      "color": "#F97316",
      "pinStyle": "teardrop",
      "zoomRange": { "min": 11, "max": 22 },
      "icon": { "name": "utensils", "href": "/api/v1/map/icons/sprite.svg#navvo-icon-utensils" }
    }
  ]
}

GET /map/icons/sprite.svg & sprite.json

sprite.svg تُعيد صورة رموز مركَّبة بصيغة SVG (image/svg+xml) لجميع الأيقونات النشطة (<symbol id="navvo-icon-…">). وsprite.json تُعيد البيان الذي يصف كل أيقونة (name، id، href، الحجم).

GET /map/readiness

تدقيق ذاتي لسطح الخريطة — قائمة من الفحوص المنطقية checks إضافةً إلى summary (أعداد الأنماط الأساسية، الطبقات العلوية، الفئات، الأيقونات). مفيد للتشخيص.

GET /map/poi

تحدّد أي الأماكن ينبغي أن تعرضها نافذة العرض فعلياً. فبإعطائها مربّعاً حدودياً ومستوى تقريب، تعيد مجموعة من نقاط الاهتمام مرتّبة حسب الأولوية ومحكومة بميزانية تسميات — لا مجرّد أقرب N صفّاً.

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

curl -s "https://navvo.io/api/v1/map/poi?bbox=35.85,31.93,35.97,32.00&zoom=15" \
  -H "x-api-key: nvvo_YOUR_KEY"

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

الاستجابة

{
  "zoom": 15,
  "budget": 180,
  "minPriority": 35,
  "profile": { "clusterRadius": 0, "labelSpacing": 12, "iconOnlyBelow": 40 },
  "items": [
    {
      "id": "98506109-374d-4810-a148-e0b7add768ac",
      "slug": "telescope-medical-center-…-fad9f9",
      "name": "Telescope Medical Center",
      "canonicalCategorySlug": "medical-center",
      "categories": ["medical-center"],
      "priority": 73,
      "rating": 4.9,
      "reviewCount": 2594,
      "lng": 35.867637,
      "lat": 31.960408,
      "labelHidden": false,
      "iconLightUrl": "https://navvo.io/uploads/category-icons/medical-center-light.svg",
      "iconDarkUrl": "https://navvo.io/uploads/category-icons/medical-center-dark.svg"
    }
  ],
  "clusters": [],
  "truncated": false
}

الطبقات العلوية

تقدِّم الطبقات العلوية العامة عناصر الخريطة المخزَّنة على هيئة GeoJSON، أو بلاطات متجهية، أو نقطية. تشمل أنواع الطبقات المعروفة traffic، transit، biking، terrain، incidents، speed_cameras، traffic_cameras، traffic_lights، weather، وlogistics_zones.

GET /map/overlays/{layerType}

FeatureCollection بصيغة GeoJSON لطبقة علوية واحدة. يقبل bbox، limit، zoom.

{
  "type": "FeatureCollection",
  "features": [
    { "type": "Feature", "geometry": { "type": "Point", "coordinates": [35.91, 31.95] },
      "properties": { "id": 12, "name": "Amman central speed camera", "layerType": "speed_cameras", "color": "#B91C1C" } }
  ],
  "metadata": { "layerType": "speed_cameras", "name": "Speed cameras", "hasData": true }
}

الوصول المُبلَّط للطبقات العلوية

GET /map/logistics-zones.geojson

مضلَّعات مناطق اللوجستيات / اتفاقية مستوى الخدمة (SLA) على هيئة GeoJSON. يحمل كل عنصر zoneType، وriskScore، وcostMultiplier، وroutingPolicy — وهي المناطق نفسها التي تظهر في نتائج /routing/plan.

الطقس

طبقات الطقس العلوية هي مضلَّعات مخزَّنة إضافةً إلى بحث نقطي حي. type ∈ precipitation, temperature, clouds, storms, alerts؛ وtime ∈ -1h, now, +1h, +3h.

أيقونات الطقس

تحمل كل استجابة طقس أيقونة جاهزة للعرض، فيُظهر التطبيق الأصلي الأيقونة نفسها التي تظهر على خريطة الويب دون إعادة بناء ربط الحالات:

المُعرِّفات: clear وclear-night وpartly وcloud وrain وstorm وsnow وfog للحالات الجوية، وheat وcold وwind للتنبيهات المُشتقّة.

https://navvo.io/uploads/weather-icons/{slug}-{light|dark}.svg

• ملفات SVG بمقاس 24 × 24 بلا أي مراجع خارجية، فيمكن تخزينها مؤقتًا أو تلوينها أو تحويلها إلى نقطية بأي حجم.
• الروابط مطلقة لأن الملفات تُقدَّم من جذر الموقع لا من تحت /api/v1؛ فحلّ مسار نسبي على بادئة الواجهة يعطي 404.
• اختر النسخة حسب سِمة واجهتك، لا حسب الليل والنهار — فالليل والنهار محمولان في المُعرِّف أصلًا: تُعيد السماء الصافية clear نهارًا وclear-night بعد الغروب.
• قد يكون icon أدقّ من النص الوصفي: يُعاد partly للسماء الصافية جزئيًا والغائمة جزئيًا، وكلاهما يُقرأ «غيوم» على المستوى الأعمّ.
• تعامل مع قائمة المُعرِّفات على أنها مفتوحة؛ قد تُضاف عائلات جديدة، فارجع إلى cloud عند قيمة غير معروفة بدل الفشل.
• تحمل مضلَّعات الطقس (/map/weather/geojson) الأيقونات مرة واحدة في metadata.icons مفهرسةً بنوع الطقس، بدل تكرار رابطين على كل خلية من آلاف الخلايا. أما نقاط MVT الثنائية وبلاطات SVG المُصيَّرة فلا تحمل أيقونات — فهي بكسلات أصلًا.

GET /map/weather/point

الطقس النقطي الحالي (من خدمة الطقس الخاصة بـ Navvo).

{
  "ok": true, "lat": 31.95, "lon": 35.91, "city": "Amman",
  "temperature": 28, "unit": "C", "feelsLike": 30, "humidity": 35,
  "windSpeed": 12, "windUnit": "km/h", "visibility": 16, "visibilityUnit": "km",
  "condition": "Clear sky",
  "aqi": 40, "aqiCategory": "Good", "pm25": 9, "pm10": 16, "dust": 1,
  "source": "Navvo weather point service"
}

تحمل الاستجابة أيضاً جودة هواء حيّة: aqi (مؤشر AQI الأمريكي)، وaqiCategory (Good…Hazardous)، وpm25/pm10 (ميكروغرام/م³)، وdust (ميكروغرام/م³، تركيز الغبار الصحراوي). وتكون null إذا تعذّر مصدر جودة الهواء مؤقتاً. تُعيد نقطة النهاية هذه 400 عند إحداثيات غير صالحة؛ بينما تُعيد إخفاقات المصدر الأعلى 200 مع ok:false.

GET /map/weather/forecast

توقّعات الطقس بالساعة لنقطة — الساعات N القادمة (افتراضي 24، أقصى 72).

{
  "ok": true, "lat": 31.95, "lon": 35.91, "city": "Amman",
  "units": "metric", "unit": "C", "windUnit": "km/h", "hours": 6,
  "forecast": [
    { "time": "2026-06-27T19:00:00.000Z", "temperature": 22.8, "condition": "Clear", "precipitationMm": 0, "windSpeed": 9, "humidity": 38 },
    { "time": "2026-06-27T20:00:00.000Z", "temperature": 22, "condition": "Clear", "precipitationMm": 0, "windSpeed": 8, "humidity": 41 }
  ]
}

400 عند إحداثيات غير صالحة؛ وإخفاقات المصدر الأعلى تُعيد 200 مع ok:false وforecast فارغة.

GET /map/weather/alerts

تحذيرات طقس مُشتقّة لنقطة — تفحص الساعات N القادمة من التوقّعات وتعيد تنبيهات عند تجاوز العتبات: حرارة (≥37°م، مهمّة خصوصاً للمنطقة)، برد/تجمّد (≤1°م)، مطر غزير (≥4مم/س)، ورياح قوية (≥40كم/س). يحمل كل تنبيه severity (moderate/high/severe) وقيمة الذروة والساعة التي يقع فيها.

?lat=&lng=&hours= (افتراضي 24، أقصى 72).

{
  "ok": true, "provider": "navvo-weather", "lat": 24.63, "lon": 46.72, "city": "…",
  "checkedHours": 48, "count": 1,
  "alerts": [
    { "type": "heat", "severity": "severe", "message": "High temperatures up to 43°C", "valueC": 43, "at": "2026-06-28T12:00:00.000Z" }
  ]
}

count: 0 (وalerts فارغة) يعني عدم تجاوز أي عتبة في النافذة. و400 عند إحداثيات غير صالحة.

GET /map/weather/cities

دبابيس طقس للمدن والبلدات داخل المنطقة المعروضة — تُستخدم لعرض الأحوال الحالية على الخريطة عند تكبير مستوى المدينة. تُعيد FeatureCollection من النقاط؛ ولا تكون ذات معنى إلا عند zoom ≥ 7 (المستويات الأقل تُعيد مجموعة فارغة بسرعة)، والعدد محدود ليبقى المشهد مقروءًا.

{
  "type": "FeatureCollection",
  "features": [
    { "type": "Feature", "geometry": { "type": "Point", "coordinates": [35.93, 31.95] },
      "properties": { "name": "Amman", "temperature": 30, "unit": "C", "condition": "Clear",
        "code": 0, "icon": "clear", "color": "#386BFF" } }
  ],
  "metadata": { "layerType": "weather_cities", "name": "Weather", "hasData": true }
}

الحقل icon عائلة محايدة — إحدى clear أو cloud أو rain أو storm أو snow أو fog — وcode مكافئها الرقمي (0–5).

GET /map/airquality/cities

دبابيس جودة الهواء (مؤشر AQI الأمريكي + الغبار) للمدن والبلدات داخل المنطقة المعروضة — وهي نظير /map/weather/cities لعرض جودة الهواء على الخريطة عند تكبير مستوى المدينة. تُعيد FeatureCollection من النقاط؛ ولا تكون ذات معنى إلا عند zoom ≥ 7، والعدد محدود (الحد الأقصى 20). القيم مخزَّنة مؤقتًا ~15 دقيقة لكل خلية.

{
  "type": "FeatureCollection",
  "features": [
    { "type": "Feature", "geometry": { "type": "Point", "coordinates": [35.92, 31.95] },
      "properties": { "name": "Amman", "aqi": 40, "aqiCategory": "Good",
        "pm25": 10, "pm10": 16, "dust": 1 } }
  ],
  "metadata": { "layerType": "air_quality_cities", "name": "Air quality", "hasData": true }
}

aqi هو مؤشر جودة الهواء الأمريكي؛ وaqiCategory فئته (Good، Moderate، Unhealthy (sensitive)، Unhealthy، Very unhealthy، Hazardous). أما pm25/pm10/dust فبوحدة µg/m³. والقيم نفسها لكل نقطة تغذّي حقلَي aqi/dust في /map/weather/point.

مخاطر المسار والإنفاذ

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

POST /map/route-risk

النطاق: routing.

جسم الطلب

{
  "routeId": "trip-42",
  "timeOffset": "+1h",
  "geometry": { "type": "LineString", "coordinates": [[35.91,31.95],[35.93,31.97],[35.95,31.99]] }
}

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

{
  "ok": true,
  "routeId": "trip-42",
  "hasRouteGeometry": true,
  "timeOffset": "+1h",
  "scores": { "overall": 24, "traffic": 40, "weather": 10, "incidents": 0, "logistics": 32, "cameras": 16 },
  "severity": "low",
  "stack": [
    { "key": "traffic", "label": "Traffic speed", "score": 40, "severity": "medium", "detail": "Moderate congestion exposure on this route.", "count": 3 }
  ],
  "warnings": [
    { "type": "traffic", "severity": "high", "title": "Heavy traffic segment", "detail": "18 km/h average · 42 samples", "location": { "lng": 35.93, "lat": 31.97 } },
    { "type": "logistics", "severity": "medium", "title": "Amman core congestion SLA", "location": { "lng": 35.91, "lat": 31.97 } }
  ]
}

POST /map/route-enforcement

النطاق: routing. تُعيد فقط نقاط تفتيش الإنفاذ (كاميرات السرعة، كاميرات حركة المرور، إشارات المرور) على امتداد المسار. جسم الطلب نفسه الخاص بمخاطر المسار.

{
  "ok": true,
  "routeId": "trip-42",
  "count": 2,
  "items": [
    { "id": "speed_camera-0", "type": "speed_camera", "title": "Amman central speed camera", "detail": "Speed camera on or near route · 60 km/h", "confidence": 0.84, "location": { "lng": 35.92, "lat": 31.96 } }
  ]
}