النقل العام والتنقل الخفيف والوضع دون اتصال
النقل العام والتنقل الخفيف والوضع دون اتصال
انقل الناس آخر ميل وأبقِ الخريطة حيّة حيث تنقطع الشبكة. تكشف هذه الوحدة عن خلاصات نقل 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
معاملات الاستعلام
500؛ ويُقيَّد من جهة الخادم لأجل وضوح العرض.الاستجابة
| الحقل | النوع | الوصف |
|---|---|---|
provider | string | دائمًا navvo-transit. |
count | number | عدد المحطات المُعادة. |
stops[] | array | المحطات القريبة، الأقرب أولًا. |
كل عنصر في stops[]:
| الحقل | النوع | الوصف |
|---|---|---|
id | string | معرّف محطة Navvo. |
stopId | string | معرّف المحطة الثابت على مستوى الخلاصة (استخدمه مع routeId للمسار). |
name | string | اسم المحطة. |
lat / lng | number | موقع المحطة. |
distanceM | number | المسافة من مركز البحث، بالأمتار. |
routeIds | string | معرّفات المسارات التي تخدم هذه المحطة. |
{
"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
معاملات الاستعلام
west,south,east,north. تُعاد فقط المسارات التي يمرّ شكلها عبر الصندوق (وتُبقى المسارات بلا هندسة).route_type في GTFS: 0 ترام، 1 مترو، 2 سكة، 3 حافلة، 4 عبّارة، … ويحمل كل مسار مُعاد typeLabel بشرياً أيضاً.تُعيد الاستجابة المرشّحات الفعّالة filters ({ type, bbox }). ادمجها — مثل ?bbox=…&type=1 لخطوط المترو فقط في النطاق.
الاستجابة
| الحقل | النوع | الوصف |
|---|---|---|
provider | string | دائمًا navvo-transit. |
count | number | عدد المسارات المُعادة. |
routes[] | array | خطوط المسارات (انظر أدناه). |
كل عنصر في routes[]:
| الحقل | النوع | الوصف |
|---|---|---|
id | string | معرّف مسار Navvo. |
routeId | string | معرّف المسار الثابت على مستوى الخلاصة (يطابق stops[].routeIds). |
shortName | string | تسمية قصيرة (مثل Blue، 300). |
longName | string | الاسم الكامل للمسار. |
type | string | الوسيلة: metro، bus، tram، rail، أو ferry. |
color | string | لون الخط بصيغة hex. |
shape | string | خط متعدد الأضلاع مُرمَّز لهندسة المسار. |
{
"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
معاملات الاستعلام
500.bike، أو ebike، أو scooter. احذفه لإعادة جميع الأنواع.minBikes=1 لإخفاء المحطات الفارغة عندما يريد الراكب أخذ مركبة الآن.minDocks.)الاستجابة
| الحقل | النوع | الوصف |
|---|---|---|
provider | string | دائمًا navvo-micromobility. |
filters | object | المرشّحات الفعّالة المُعادة: { vehicleType, minBikes, minDocks }. |
count | number | عدد المحطات المُعادة. |
stations[] | array | المحطات القريبة، الأقرب أولًا — لكلٍّ bikesAvailable / docksAvailable. |
كل عنصر في stations[]:
| الحقل | النوع | الوصف |
|---|---|---|
id | string | معرّف محطة Navvo. |
name | string | اسم المحطة. |
vehicleType | string | bike، أو ebike، أو scooter. |
lat / lng | number | موقع المحطة. |
bikesAvailable | number | المركبات المتاحة للاستلام الآن. |
docksAvailable | number | الأرصفة الفارغة لإعادة مركبة (0 للمحطات دون رصيف / الحرّة). |
distanceM | number | المسافة من مركز البحث، بالأمتار. |
{
"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
جسم الطلب
{ lat, lng }.{ lat, lng }.الاستجابة — وُجِد اتصال
| الحقل | النوع | الوصف |
|---|---|---|
provider | string | دائمًا navvo-transit. |
found | boolean | true عند العثور على مسار واصل. |
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 سببًا، وبديل مشي مباشر، وأقرب المحطات عند كل طرف كي تحثّ الراكب على النقل العام رغم ذلك.
| الحقل | النوع | الوصف |
|---|---|---|
found | boolean | false. |
reason | string | سبب عدم إعادة رحلة نقل (مثل no_common_route، out_of_coverage). |
walkAlternative | object | مقطع مشي مباشر { 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
الاستجابة
| الحقل | النوع | الوصف |
|---|---|---|
provider | string | دائمًا navvo-offline. |
regions[] | array | مناطق العمل دون اتصال المتاحة (انظر أدناه). |
كل عنصر في regions[]:
| الحقل | النوع | الوصف |
|---|---|---|
id | string | معرّف المنطقة (استخدمه مع /offline/regions/{id}/manifest). |
name | string | الاسم بالإنجليزية. |
nameAr | string | الاسم بالعربية. |
bbox | number | الحدود بالصيغة [west, south, east, north]. |
minZoom / maxZoom | number | مدى التكبير المُعبَّأة له المنطقة. |
estTiles | number | العدد التقديري للبلاطات المطلوب تنزيلها. |
estSizeMb | number | الحجم التقديري للتنزيل بالميغابايت. |
countryCode | string | رمز الدولة ISO (مثل SA، JO، AE). |
scope | string | country أو city. |
version | string | رمز إصدار — يتغيّر كلما حُدِّثت الحزمة. قارنه بتنزيل مخزَّن لعرض «تحديث متاح». |
{
"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
الاستجابة
| الحقل | النوع | الوصف |
|---|---|---|
provider | string | دائمًا navvo-offline. |
region | object | واصف المنطقة (الشكل نفسه لعنصر في /offline/regions). |
styleUrl | string | رابط نمط الخريطة للتخزين والعرض دون اتصال. |
vectorTileTemplate | string | قالب رابط البلاطات المتجهية — وسّع {z}/{x}/{y} عبر bbox × zooms. |
glyphs | object | خطوط الحروف اللازمة للتسميات دون اتصال: template (قالب رابط {fontstack}/{range})، وfontstacks (حِزم الخطوط التي يستخدمها النمط)، وranges (نطاقات يونيكود المطلوب جلبها — كتل لاتينية + عربية، فتُعرض التسميات بالإنجليزية والعربية دون اتصال). خزّن كل تركيبة fontstack × range. |
sprite | object | أطلس الأيقونات: روابط json (الفهرس) وpng وpng2x (دقة عالية) — خزّن الثلاثة. |
rasterTemplates | object | قوالب البلاطات النقطية (standard، satellite) للعملاء الذين يريدون أيضاً بديلاً نقطياً/فضائياً دون اتصال. اختياري — الخريطة المتجهية وحدها تُعرض كاملةً دون اتصال. |
tiles | number | العدد التقديري للبلاطات المتجهية لتنزيل كامل الـbbox × التكبيرات. |
sizeMb | number | الحجم التقديري للتنزيل بالميغابايت. |
zooms | object | { min, max } — مستويات التكبير المطلوب تنزيلها. يتجاوز العارض max بالتكبير الزائد (overzoom)، فتظل التكبيرات الأعمق تُعرض من البلاطات المخزّنة. |
version | string | رمز إصدار الحزمة — أعِد جلب البيان وقارِن لعرض «تحديث متاح». |
bbox | number | حدود المنطقة [west, south, east, north]. |
note | string | إرشاد تخزين للعميل. |
{
"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."
}
GET /search / GET /places الأخيرة) إلى جانب حزمة الخريطة.x-api-key — ألحِق ?api_key=nvvo_YOUR_KEY عند توسيع styleUrl وقوالب البلاطات/الخطوط/الأيقونات. انظر بلاطات الخريطة والأنماط للتفاصيل.