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

النقل العام والتنقل الخفيف والوضع دون اتصال

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

النقل العام والتنقل الخفيف والوضع دون اتصال

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

كل شيء يقدِّمه Navvo ويحمل علامته من واجهة برمجية واحدة. لا توجد خدمات خارجية لربطها.

النطاق المطلوب: places للمحطات والمسارات ومحطات التنقل؛ و**routing** لتخطيط الرحلات؛ و**tiles** لمناطق العمل دون اتصال وبياناتها.

الإحداثيات بالدرجات العشرية (lat، lng). حقول المسافة (distanceM) بالأمتار. صندوق الإحاطة bbox بالصيغة west,south,east,north. تقبل نقاط النهاية القريبة معامل radius بالأمتار. تتدرج نقاط النهاية بلطف — نطاق رؤية خارج التغطية يُعيد مجموعة فارغة count:0 بدل خطأ.

GET /transit/stops

محطات النقل العام القريبة (مترو، حافلة، ترام، قطار) حول نقطة — المحطات التي ترسمها كعلامات قرب المستخدم أو تستخدمها كنقاط انطلاق للرحلات. كل محطة تُدرج routeIds للمسارات التي تخدمها.

curl -s "https://navvo.io/api/v1/transit/stops?lat=24.7136&lng=46.6753&radius=800" \
  -H "x-api-key: nvvo_YOUR_KEY"

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

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

lat
number required
خط عرض مركز البحث.
lng
number required
خط طول مركز البحث.
radius
number
نصف قطر البحث بالأمتار. القيمة الافتراضية 500؛ ويُقيَّد من جهة الخادم لأجل وضوح العرض.

الاستجابة

الحقلالنوعالوصف
providerstringدائمًا navvo-transit.
countnumberعدد المحطات المُعادة.
stops[]arrayالمحطات القريبة، الأقرب أولًا.

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

الحقلالنوعالوصف
idstringمعرّف محطة Navvo.
stopIdstringمعرّف المحطة الثابت على مستوى الخلاصة (استخدمه مع routeId للمسار).
namestringاسم المحطة.
lat / lngnumberموقع المحطة.
distanceMnumberالمسافة من مركز البحث، بالأمتار.
routeIdsstringمعرّفات المسارات التي تخدم هذه المحطة.
{
  "provider": "navvo-transit",
  "count": 2,
  "stops": [
    {
      "id": "stop-9a31",
      "stopId": "RYD-METRO-1-OLAYA",
      "name": "Olaya",
      "lat": 24.6913,
      "lng": 46.6857,
      "distanceM": 142,
      "routeIds": ["RYD-METRO-BLUE"]
    },
    {
      "id": "stop-7c08",
      "stopId": "RYD-BUS-300-KINGFAHD",
      "name": "King Fahd Rd",
      "lat": 24.6951,
      "lng": 46.6840,
      "distanceM": 410,
      "routeIds": ["RYD-BUS-300", "RYD-BUS-305"]
    }
  ]
}

GET /transit/routes

خطوط المسارات لنطاق رؤية — الخطوط المتعددة الأضلاع الملوّنة التي تركِّبها على الخريطة لرسم شبكة مترو أو باص سريع. يحمل كل مسار شكلًا مُرمَّزًا shape يمكنك عرضه مباشرةً.

curl -s "https://navvo.io/api/v1/transit/routes?bbox=46.55,24.60,46.80,24.80" \
  -H "x-api-key: nvvo_YOUR_KEY"

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

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

bbox
string
حدود نطاق الرؤية west,south,east,north. تُعاد فقط المسارات التي يمرّ شكلها عبر الصندوق (وتُبقى المسارات بلا هندسة).
type
number
تصفية حسب route_type في GTFS: 0 ترام، 1 مترو، 2 سكة، 3 حافلة، 4 عبّارة، … ويحمل كل مسار مُعاد typeLabel بشرياً أيضاً.
q
string
تصفية غير حسّاسة لحالة الأحرف على اسم المسار القصير/الطويل.

تُعيد الاستجابة المرشّحات الفعّالة filters ({ type, bbox }). ادمجها — مثل ?bbox=…&type=1 لخطوط المترو فقط في النطاق.

الاستجابة

الحقلالنوعالوصف
providerstringدائمًا navvo-transit.
countnumberعدد المسارات المُعادة.
routes[]arrayخطوط المسارات (انظر أدناه).

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

الحقلالنوعالوصف
idstringمعرّف مسار Navvo.
routeIdstringمعرّف المسار الثابت على مستوى الخلاصة (يطابق stops[].routeIds).
shortNamestringتسمية قصيرة (مثل Blue، 300).
longNamestringالاسم الكامل للمسار.
typestringالوسيلة: metro، bus، tram، rail، أو ferry.
colorstringلون الخط بصيغة hex.
shapestringخط متعدد الأضلاع مُرمَّز لهندسة المسار.
{
  "provider": "navvo-transit",
  "count": 1,
  "routes": [
    {
      "id": "route-blue",
      "routeId": "RYD-METRO-BLUE",
      "shortName": "Blue",
      "longName": "Riyadh Metro — Line 1 (Blue)",
      "type": "metro",
      "color": "#1E61F0",
      "shape": "qkn~Eqd}xK}@a@k@e@_@e@"
    }
  ]
}
shape خط متعدد الأضلاع مُرمَّز قياسي (دقة 5). فُكَّ ترميزه إلى أزواج [lat, lng] لرسم الخط، أو سلِّمه إلى عارض Navvo Maps كمصدر LineString.

GET /transit/gbfs

محطات التنقل الخفيف المشترك القريبة — دراجات بأرصفة، ودراجات كهربائية، وسكوترات في دول الخليج — مع أعداد توفّر حيّة. استخدمها لإظهار أماكن استلام مركبة الآن للراكبين.

curl -s "https://navvo.io/api/v1/transit/gbfs?lat=25.2048&lng=55.2708&radius=600&type=scooter" \
  -H "x-api-key: nvvo_YOUR_KEY"

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

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

lat
number required
خط عرض مركز البحث.
lng
number required
خط طول مركز البحث.
radius
number
نصف قطر البحث بالأمتار. القيمة الافتراضية 500.
type
string
ترشيح حسب نوع المركبة: bike، أو ebike، أو scooter. احذفه لإعادة جميع الأنواع.
minBikes
number
فقط المحطات التي بها هذا العدد على الأقل من المركبات المتاحة للاستلام. استخدم minBikes=1 لإخفاء المحطات الفارغة عندما يريد الراكب أخذ مركبة الآن.
minDocks
number
فقط المحطات التي بها هذا العدد على الأقل من المرابط الفارغة — لراكب يحتاج مكاناً للإرجاع/الركن. (الأنظمة بلا مرابط لا تُبلّغ عن مرابط، فتُستبعَد عند ضبط minDocks.)

الاستجابة

الحقلالنوعالوصف
providerstringدائمًا navvo-micromobility.
filtersobjectالمرشّحات الفعّالة المُعادة: { vehicleType, minBikes, minDocks }.
countnumberعدد المحطات المُعادة.
stations[]arrayالمحطات القريبة، الأقرب أولًا — لكلٍّ bikesAvailable / docksAvailable.

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

الحقلالنوعالوصف
idstringمعرّف محطة Navvo.
namestringاسم المحطة.
vehicleTypestringbike، أو ebike، أو scooter.
lat / lngnumberموقع المحطة.
bikesAvailablenumberالمركبات المتاحة للاستلام الآن.
docksAvailablenumberالأرصفة الفارغة لإعادة مركبة (0 للمحطات دون رصيف / الحرّة).
distanceMnumberالمسافة من مركز البحث، بالأمتار.
{
  "provider": "navvo-micromobility",
  "count": 2,
  "stations": [
    {
      "id": "mm-4471",
      "name": "Dubai Marina Walk",
      "vehicleType": "scooter",
      "lat": 25.0805,
      "lng": 55.1403,
      "bikesAvailable": 6,
      "docksAvailable": 0,
      "distanceM": 88
    },
    {
      "id": "mm-4490",
      "name": "JBR Station",
      "vehicleType": "ebike",
      "lat": 25.0789,
      "lng": 55.1340,
      "bikesAvailable": 3,
      "docksAvailable": 9,
      "distanceM": 520
    }
  ]
}

POST /transit/plan

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

curl -s "https://navvo.io/api/v1/transit/plan" \
  -H "x-api-key: nvvo_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": { "lat": 31.9539, "lng": 35.9106 },
    "to":   { "lat": 31.9870, "lng": 35.8650 }
  }'

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

جسم الطلب

from
object required
نقطة الانطلاق { lat, lng }.
to
object required
الوجهة { lat, lng }.

الاستجابة — وُجِد اتصال

الحقلالنوعالوصف
providerstringدائمًا navvo-transit.
foundbooleantrue عند العثور على مسار واصل.
legs[]arrayمقاطع الرحلة بالترتيب: مقطع walk، ثم مقطع transit، ثم مقطع walk.

يحمل مقطع transit المسار route الذي يستخدمه (كائن مسار كما في /transit/routes) إضافةً إلى محطتي board (الركوب) وalight (النزول) (كائنات محطات كما في /transit/stops). أما مقاطع walk فتحمل مسافتها ومدتها الخاصتين.

{
  "provider": "navvo-transit",
  "found": true,
  "legs": [
    {
      "mode": "walk",
      "from": { "lat": 31.9539, "lng": 35.9106 },
      "to":   { "lat": 31.9551, "lng": 35.9119 },
      "distanceM": 210,
      "durationS": 168
    },
    {
      "mode": "transit",
      "route": {
        "routeId": "AMM-BRT-1",
        "shortName": "BRT 1",
        "longName": "Amman BRT — Sweileh Corridor",
        "type": "bus",
        "color": "#0EA15B"
      },
      "board":  { "stopId": "AMM-BRT-1-ABDALI", "name": "Abdali", "lat": 31.9551, "lng": 35.9119 },
      "alight": { "stopId": "AMM-BRT-1-SWEIFIEH", "name": "Sweifieh", "lat": 31.9860, "lng": 35.8669 },
      "durationS": 720
    },
    {
      "mode": "walk",
      "from": { "lat": 31.9860, "lng": 35.8669 },
      "to":   { "lat": 31.9870, "lng": 35.8650 },
      "distanceM": 240,
      "durationS": 192
    }
  ]
}

الاستجابة — لا يوجد اتصال

عندما لا يلائم أي مسار واصل، تكون found بقيمة false ويُعيد Navvo سببًا، وبديل مشي مباشر، وأقرب المحطات عند كل طرف كي تحثّ الراكب على النقل العام رغم ذلك.

الحقلالنوعالوصف
foundbooleanfalse.
reasonstringسبب عدم إعادة رحلة نقل (مثل no_common_route، out_of_coverage).
walkAlternativeobjectمقطع مشي مباشر { distanceM, durationS }.
nearestOriginStops[]arrayأقرب المحطات إلى نقطة الانطلاق (كائنات محطات).
nearestDestStops[]arrayأقرب المحطات إلى الوجهة (كائنات محطات).
{
  "provider": "navvo-transit",
  "found": false,
  "reason": "no_common_route",
  "walkAlternative": { "distanceM": 5400, "durationS": 4320 },
  "nearestOriginStops": [
    { "stopId": "AMM-BUS-26-DOWNTOWN", "name": "Downtown", "lat": 31.9515, "lng": 35.9239, "distanceM": 310 }
  ],
  "nearestDestStops": [
    { "stopId": "AMM-BUS-26-SHMEISANI", "name": "Shmeisani", "lat": 31.9700, "lng": 35.9000, "distanceM": 480 }
  ]
}

GET /offline/regions

فهرس مناطق الخريطة للعمل دون اتصال المعرّفة مسبقًا والقابلة للتنزيل — مناطق محدودة يمكن للعميل تخزينها مسبقًا كي تبقى الخريطة تعمل دون شبكة. استخدمه لعرض مُنتقي «تنزيل للعمل دون اتصال» (دولة كاملة أو مدينة).

curl -s "https://navvo.io/api/v1/offline/regions" \
  -H "x-api-key: nvvo_YOUR_KEY"

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

الاستجابة

الحقلالنوعالوصف
providerstringدائمًا navvo-offline.
regions[]arrayمناطق العمل دون اتصال المتاحة (انظر أدناه).

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

الحقلالنوعالوصف
idstringمعرّف المنطقة (استخدمه مع /offline/regions/{id}/manifest).
namestringالاسم بالإنجليزية.
nameArstringالاسم بالعربية.
bboxnumberالحدود بالصيغة [west, south, east, north].
minZoom / maxZoomnumberمدى التكبير المُعبَّأة له المنطقة.
estTilesnumberالعدد التقديري للبلاطات المطلوب تنزيلها.
estSizeMbnumberالحجم التقديري للتنزيل بالميغابايت.
countryCodestringرمز الدولة ISO (مثل SA، JO، AE).
scopestringcountry أو city.
versionstringرمز إصدار — يتغيّر كلما حُدِّثت الحزمة. قارنه بتنزيل مخزَّن لعرض «تحديث متاح».
{
  "provider": "navvo-offline",
  "regions": [
    {
      "id": "05f81944-b193-4fb2-a61d-af3c96b91af4",
      "name": "Jordan",
      "nameAr": "الأردن",
      "scope": "country",
      "bbox": [34.88, 29.18, 39.30, 33.38],
      "minZoom": 5,
      "maxZoom": 12,
      "estTiles": 3999,
      "estSizeMb": 117,
      "countryCode": "JO",
      "version": "2026-06-25T14:55:16.529Z"
    },
    {
      "id": "d86f0ed5-9821-43cc-af67-e5c8fa0ff429",
      "name": "Palestine",
      "nameAr": "فلسطين",
      "scope": "country",
      "bbox": [34.22, 31.22, 35.57, 32.55],
      "minZoom": 5,
      "maxZoom": 12,
      "estTiles": 446,
      "estSizeMb": 13,
      "countryCode": "PS",
      "version": "2026-06-25T14:55:16.529Z"
    }
  ]
}

GET /offline/regions/{id}/manifest

بيان التنزيل لمنطقة واحدة — كل ما يحتاجه العميل للتخزين المسبق لخريطة أساس كاملة دون اتصال: النمط، البلاطات المتجهية، الخطوط (glyphs) والأيقونات (sprite) والبدائل النقطية. اجلبه بعد اختيار المستخدم منطقةً، ثم عدِّد البلاطات عبر bbox × zooms واملأ تخزينك المؤقت.

curl -s "https://navvo.io/api/v1/offline/regions/{id}/manifest" \
  -H "x-api-key: nvvo_YOUR_KEY"

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

الاستجابة

الحقلالنوعالوصف
providerstringدائمًا navvo-offline.
regionobjectواصف المنطقة (الشكل نفسه لعنصر في /offline/regions).
styleUrlstringرابط نمط الخريطة للتخزين والعرض دون اتصال.
vectorTileTemplatestringقالب رابط البلاطات المتجهية — وسّع {z}/{x}/{y} عبر bbox × zooms.
glyphsobjectخطوط الحروف اللازمة للتسميات دون اتصال: template (قالب رابط {fontstack}/{range})، وfontstacks (حِزم الخطوط التي يستخدمها النمط)، وranges (نطاقات يونيكود المطلوب جلبها — كتل لاتينية + عربية، فتُعرض التسميات بالإنجليزية والعربية دون اتصال). خزّن كل تركيبة fontstack × range.
spriteobjectأطلس الأيقونات: روابط json (الفهرس) وpng وpng2x (دقة عالية) — خزّن الثلاثة.
rasterTemplatesobjectقوالب البلاطات النقطية (standard، satellite) للعملاء الذين يريدون أيضاً بديلاً نقطياً/فضائياً دون اتصال. اختياري — الخريطة المتجهية وحدها تُعرض كاملةً دون اتصال.
tilesnumberالعدد التقديري للبلاطات المتجهية لتنزيل كامل الـbbox × التكبيرات.
sizeMbnumberالحجم التقديري للتنزيل بالميغابايت.
zoomsobject{ min, max } — مستويات التكبير المطلوب تنزيلها. يتجاوز العارض max بالتكبير الزائد (overzoom)، فتظل التكبيرات الأعمق تُعرض من البلاطات المخزّنة.
versionstringرمز إصدار الحزمة — أعِد جلب البيان وقارِن لعرض «تحديث متاح».
bboxnumberحدود المنطقة [west, south, east, north].
notestringإرشاد تخزين للعميل.
{
  "provider": "navvo-offline",
  "region": { "id": "", "name": "Jordan", "nameAr": "الأردن", "scope": "country",
              "bbox": [34.88, 29.18, 39.30, 33.38], "minZoom": 5, "maxZoom": 12,
              "estTiles": 3999, "estSizeMb": 117, "countryCode": "JO", "version": "2026-06-25T14:55:16.529Z" },
  "styleUrl": "/api/v1/tiles/style?style=standard",
  "vectorTileTemplate": "/api/v1/tiles/vector/navvo/planet/{z}/{x}/{y}.pbf",
  "glyphs": {
    "template": "/api/v1/tiles/glyphs/navvo/{fontstack}/{range}.pbf",
    "fontstacks": ["Noto Sans Regular", "Noto Sans Bold"],
    "ranges": ["0-255", "256-511", "1536-1791", "1792-2047", "64256-64511", "65024-65279"]
  },
  "sprite": {
    "json": "/api/v1/tiles/sprites/navvo/sprite.json",
    "png": "/api/v1/tiles/sprites/navvo/sprite.png",
    "png2x": "/api/v1/tiles/sprites/navvo/sprite@2x.png"
  },
  "rasterTemplates": {
    "standard": "/api/v1/tiles/raster/standard/{z}/{x}/{y}.png",
    "satellite": "/api/v1/tiles/raster/satellite/{z}/{x}/{y}.png"
  },
  "tiles": 3999,
  "sizeMb": 117,
  "zooms": { "min": 5, "max": 12 },
  "version": "2026-06-25T14:55:16.529Z",
  "bbox": [34.88, 29.18, 39.30, 33.38],
  "note": "Cache vector tiles across bbox × zooms (plus glyphs/sprite above) for a complete offline base map; the map overzooms past the cached level."
}
البحث عن الأماكن دون اتصال ميزة لدى العميل، وليس جزءاً من البيان. يغطي البيان خريطة الأساس فقط (البلاطات والنمط والخطوط والأيقونات) — ولا يحمل أي فهرس بحث عن الأماكن. يطبّق تطبيق Navvo (PWA) البحث دون اتصال من جهة العميل؛ فإذا احتاج تطبيقك ذلك، خزّن بيانات أماكنك بنفسك (مثلاً استجابات GET /search / GET /places الأخيرة) إلى جانب حزمة الخريطة.
روابط البيان نسبية، وهي — ككل موارد الخريطة — تُجلب مباشرةً من العارض الذي لا يمكنه إرسال ترويسة x-api-key — ألحِق ?api_key=nvvo_YOUR_KEY عند توسيع styleUrl وقوالب البلاطات/الخطوط/الأيقونات. انظر بلاطات الخريطة والأنماط للتفاصيل.
Copyright © 2026