التوجيه
التوجيه
الاتجاهات وتحليل المسارات، مدعومة بمحرّك التوجيه لدى Navvo. توفّر الواجهة البرمجية تمريراً منخفض المستوى إلى محرّك التوجيه (/route، /matrix، /isochrone، /map-match، /optimize) ومخطِّطاً عالي المستوى من Navvo (/plan) يبني الطلب نيابةً عنك ويضيف تسميات الذكاء الاصطناعي وتحليل القيود ومخاطر مناطق اللوجستيات.
النطاق المطلوب: routing
- نقاط التمرير (
/route،/matrix،/isochrone،/map-match،/optimize) تمرّرpayloadخام إلى محرّك التوجيه، لذا تستخدم المواقع كائنات محرّك التوجيه الأصلية{ "lat": …, "lon": … }(لاحظlon). - يستخدم
/planجسماً من Navvo بكائنات موقع{ "lon": …, "lat": …, "name"? }(المفاتيح مُسمّاة، لذا لا يهمّ الترتيب).
201 مع available: false. تحقّق دائماً من available.المغلّف للاستجابة
تغلّف نقاط التمرير ردّ محرّك التوجيه:
{ "provider": "navvo", "available": true, "path": "route", "data": { /* raw routing-engine response */ } }
عند فشل المحرّك:
{ "provider": "navvo", "available": false, "path": "route", "request": { /* your payload, echoed */ } }
POST /routing/* وPOST /traffic/route) تتطلب مستدعياً معرَّفاً — رمز Bearer لمستخدم Navvo مسجَّل أو مفتاح API الخاص بك (x-api-key). الطلبات المجهولة تعيد 401. تبقى GET /routing/profiles عامة.POST /routing/route
اتجاهات منعطفاً بمنعطف بين المواقع. يُوكِّل إلى /route في محرّك التوجيه ويرفق كتلة labels مولّدة بالذكاء الاصطناعي (تسمية قصيرة + نصيحة للمسار).
جسم الطلب
حقول payload الشائعة: locations (مصفوفة من {lat, lon, type?})، costing (auto، pedestrian، bicycle، truck، motor_scooter، bus، taxi، …)، costing_options، directions_options (units: kilometers/miles، language)، alternates، date_time.
{
"payload": {
"locations": [
{ "lat": 31.95, "lon": 35.91 },
{ "lat": 31.99, "lon": 35.95 }
],
"costing": "auto",
"directions_options": { "units": "kilometers", "language": "en-US" },
"alternates": 2
}
}
الاستجابة (201)
data.trip هي رحلة محرّك التوجيه القياسية — legs[].maneuvers[] (منعطفاً بمنعطف)، وlegs[].shape (خط مُرمَّز، بدقّة 1e6)، وsummary (time بالثواني، length بالوحدات المطلوبة، has_toll/has_highway/has_ferry). يحتوي كائن labels المُضاف على parsed: { label, tip } بأفضل جهد ممكن.
{
"provider": "navvo",
"available": true,
"path": "route",
"data": {
"trip": {
"legs": [ { "maneuvers": [ { "type": 1, "instruction": "Drive northeast.", "time": 120.5, "length": 1.23 } ], "summary": { "time": 540.2, "length": 5.6 }, "shape": "ityp_AdpjpC…" } ],
"summary": { "has_toll": false, "has_highway": true, "time": 540.2, "length": 5.6 },
"status": 0, "units": "kilometers", "language": "en-US"
}
},
"labels": { "purpose": "route_labels", "parsed": { "label": "Fast city route", "tip": "Light traffic, mostly highways" } }
}
POST /traffic/route بدلاً من ذلك — فهو يأخذ عيّنات من حركة المرور الحيّة لدى Navvo على طول المسار.GET /routing/profiles
كتالوج ملفات التوجيه (أوضاع costing) إضافةً إلى preferences وavoid وconstraints الممرّ المدعومة — لبناء مُنتقي وسيلة تنقّل. يحمل كل ملف راية available تعكس ما يستطيع هذا النشر توجيهه فعلاً.
curl -s "https://navvo.io/api/v1/routing/profiles" -H "x-api-key: $NAVVO_API_KEY"
{
"provider": "navvo-routing",
"profiles": [
{ "costing": "auto", "label": "Driving", "available": true, "description": "Car routing (default)." },
{ "costing": "bicycle", "label": "Cycling", "available": true },
{ "costing": "pedestrian", "label": "Walking", "available": true },
{ "costing": "wheelchair", "label": "Wheelchair", "available": true, "description": "Pedestrian profile with step/grade penalties." },
{ "costing": "truck", "label": "Truck", "available": false, "description": "Accepted by the API but requires truck-enabled routing tiles, not provisioned on this deployment." }
],
"preferences": ["fastest", "shortest", "balanced"],
"avoid": ["tolls", "highways", "ferries", "unpaved"],
"constraints": ["avoidIncidents", "avoidReported", "disregard"]
}
| الحقل | ملاحظات |
|---|---|
profiles[].costing | القيمة التي تمرّرها كـ costing إلى /routing/plan |
profiles[].available | هل يستطيع هذا النشر توجيه الملف (truck يحتاج بلاطات مفعّلة للشاحنات) |
preferences / avoid | قيم preference وavoid[] المقبولة |
constraints | رايات الممرّ (avoidIncidents، avoidReported، disregard) |
POST /routing/plan
نقطة النهاية عالية المستوى المُوصى بها. تعطيها المحطات والتفضيلات؛ فتبني طلب محرّك التوجيه، وتختار route أو optimized_route تلقائياً، وتُثري النتيجة بتسميات الذكاء الاصطناعي، وتحليل اختياري للقيود باللغة الطبيعية، وتحليل مخاطر مناطق اللوجستيات.
جسم الطلب
{ "lon": number, "lat": number, "name"?: string }. مطلوب 2 على الأقل.auto (الافتراضي)، pedestrian، bicycle، motor_scooter، truck.fastest أو shortest أو balanced (الافتراضي). يضبط خيارات التكلفة.tolls، highways، ferries، unpaved.true. تجاوز إغلاق الحلقة: بلاغات الملاحظات المعرقِلة (طريق مغلق / مفقود / مناورة غير قانونية / خطر) التي أكّدها محرّر (status: ack) والواقعة ضمن ~30م من الممر تُلتَفّ حولها في التوجيه. البلاغات غير المؤكَّدة لا تؤثّر أبداً، والمؤكَّدة تنتهي صلاحيتها تلقائياً بعد 60 يوماً. تُبلِّغ كتلة reportedConstraints في الاستجابة عمّا طُبِّق. اضبطها على false لتجاهلها.GET /road-edits/geojson) — الواقعة ضمن ~70م من الممر تُلتَفّ حولها (إغلاقات الخطوط تتحوّل إلى نقاط مُستبعَدة، وإغلاقات المناطق إلى مضلَّعات مُستبعَدة). تُبلِّغ كتلة roadEditConstraints في الاستجابة عمّا طُبِّق.true، يعيد ترتيب المحطات الوسيطة لأقصر جولة (optimized_route في محرّك التوجيه). يُستخدم التحسين أيضاً تلقائياً عند تمرير أكثر من موقعين.constraints مُهيكلة.true. اضبطها على false للحصول على استجابة فورية تُعيد هندسة المسار والمسارات البديلة فقط، متجاوزةً تسمية المسار من الذكاء الاصطناعي (التي تضيف ~1–2 ثانية). مُستحسَنة للتطبيقات التفاعلية الحسّاسة لزمن الاستجابة.en-US. عند ضبطها على الإنجليزية، تُترجَم أيضاً
أسماء الطرق في instruction وstreet_names إلى الإنجليزية (name:en ←
int_name، ثم تحويل صوتي إلى الحروف اللاتينية للاسم المحلي كحل أخير) لتظهر
الإرشادات وتُنطق دائماً بحروف لاتينية حتى حين تكون أسماء الخريطة الافتراضية
بحروف غير لاتينية (مثل العربية).{
"locations": [
{ "lon": 35.91, "lat": 31.95, "name": "Warehouse" },
{ "lon": 35.95, "lat": 31.99, "name": "Customer A" },
{ "lon": 35.88, "lat": 31.97, "name": "Customer B" }
],
"costing": "truck",
"preference": "fastest",
"avoid": ["tolls", "unpaved"],
"optimize": true,
"constraintsText": "Deliver to Customer A before 11:00, avoid downtown."
}
الاستجابة (201)
{
"provider": "navvo-routing",
"engine": { "provider": "navvo", "available": true, "path": "optimized_route", "data": { "trip": { } } },
"labels": { "parsed": { "label": "…", "tip": "…" } },
"constraints": { "purpose": "route_constraints", "content": "{\"orderedStops\":[…],\"timeWindows\":[…]}" },
"logistics": {
"applied": true,
"matchedZones": [
{ "slug": "amman-restricted", "name": "Amman Restricted Access", "zoneType": "restricted_access", "riskScore": 0.8, "costMultiplier": 1.25, "routingPolicy": "Permit required 06:00-09:00" }
],
"maxRiskScore": 0.8,
"totalCostMultiplier": 1.25,
"policySummary": "Permit required 06:00-09:00"
},
"routeProfile": { "costing": "truck", "preference": "fastest", "avoid": ["tolls", "unpaved"] }
}
| الحقل | الوصف |
|---|---|
engine | مغلّف مسار محرّك التوجيه مع data.trip الخام. path هو route أو optimized_route. عند توفّر مسارات بديلة تُعاد ضمن engine.data.alternates[] (لكل عنصر trip خاص به)، ويكون data.trip هو الأسرع. |
labels | تسمية/نصيحة المسار من الذكاء الاصطناعي. تكون فارغة عندما يكون includeLabels بقيمة false. |
constraints | يظهر فقط إذا أرسلت constraintsText؛ وإلا فهو null. |
logistics | مناطق اللوجستيات/اتفاقية مستوى الخدمة لدى Navvo التي يعبرها المسار، مع المخاطر ومُضاعِفات التكلفة. applied: false عند عدم تقاطع أيٍّ منها. |
routeProfile | صدى التكلفة/التفضيل/التجنّب المُحدَّدة. |
roadEditConstraints | { applied, blockingCount, source } — تعديلات الطرق من المنصّة (إغلاقات/قيود) التي التُفّ حولها. |
/plan دائماً الكيلومترات. تقع المسافات/المدد تحت حقل engine.data.trip.summary.POST /routing/matrix
مصفوفة زمن السفر / المسافة بين المصادر والأهداف. يُوكِّل إلى نقطة sources_to_targets في محرّك التوجيه.
جسم الطلب
{ "payload": <raw routing-engine matrix request> } — عادةً sources وtargets (مصفوفات من {lat, lon})، بالإضافة إلى costing وunits.
{
"payload": {
"sources": [ { "lat": 31.95, "lon": 35.91 }, { "lat": 31.99, "lon": 35.95 } ],
"targets": [ { "lat": 31.90, "lon": 35.93 } ],
"costing": "auto",
"units": "kilometers"
}
}
الاستجابة (201)
يحمل data.sources_to_targets[i][j] العنصر من المصدر i إلى الهدف j: time (بالثواني)، وdistance (بـ units)، وfrom_index/to_index. الأزواج غير القابلة للوصول لها time/distance بقيمة null.
{
"provider": "navvo", "available": true, "path": "sources_to_targets",
"data": {
"sources_to_targets": [
[ { "from_index": 0, "to_index": 0, "distance": 6.43, "time": 612 } ],
[ { "from_index": 1, "to_index": 0, "distance": 8.10, "time": 740 } ]
],
"units": "kilometers"
}
}
POST /routing/isochrone
مضلّعات القابلية للوصول (إلى أي مدى يمكنك السفر خلال N دقيقة). يُوكِّل إلى /isochrone في محرّك التوجيه.
جسم الطلب
{ "payload": <raw routing-engine isochrone request> } — locations ({lat, lon})، costing، contours (مصفوفة من { time: <minutes> } و/أو { distance: <km> }، وcolor اختياري)، polygons (boolean).
{
"payload": {
"locations": [ { "lat": 31.95, "lon": 35.91 } ],
"costing": "pedestrian",
"contours": [ { "time": 5 }, { "time": 10 } ],
"polygons": true
}
}
الاستجابة (201)
data هو FeatureCollection بصيغة GeoJSON. إحداثيات الهندسة بصيغة [lng, lat]؛ وproperties.contour هو قيمة الكنتور (دقائق للزمن، كيلومترات للمسافة).
{
"provider": "navvo", "available": true, "path": "isochrone",
"data": {
"type": "FeatureCollection",
"features": [
{ "type": "Feature", "properties": { "contour": 5, "metric": "time", "color": "#ff0000" },
"geometry": { "type": "Polygon", "coordinates": [ [ [35.90, 31.94], [35.92, 31.94] ] ] } }
]
}
}
POST /routing/map-match
ثبِّت أثر GPS خاماً على شبكة الطرق. يُوكِّل إلى trace_route في محرّك التوجيه (يقرأ path في المغلّف "trace_route").
جسم الطلب
{ "payload": <raw routing-engine trace_route request> } — إمّا shape (مصفوفة من {lat, lon, time?}) أو encoded_polyline، بالإضافة إلى costing وshape_match (map_snap، edge_walk، walk_or_snap).
{
"payload": {
"shape": [ { "lat": 31.9501, "lon": 35.9101 }, { "lat": 31.9520, "lon": 35.9145 } ],
"costing": "auto",
"shape_match": "map_snap"
}
}
الاستجابة (201)
data.trip هي رحلة محرّك توجيه قياسية تمثّل المسار المُطابَق (الأرجل، المنعطفات، الشكل المُرمَّز).
POST /routing/route-attributes
حدود السرعة على طول المسار — خصائص الطريق لكل حافة على امتداد شكل. أعطِه الخط المضلّع المفكوك للمسار (أو أي أثر GPS) واستلم، حافة بحافة، حد السرعة القانوني والسرعة النموذجية والطول واسم الطريق وفئته — كل ما يحتاجه عميل الملاحة لعرض حد السرعة المتغيّر مع تقدّم السائق.
جسم الطلب
| الحقل | النوع | ملاحظات |
|---|---|---|
shape | array | مطلوب — نقطتان { "lat": …, "lon": … } على الأقل (بحد أقصى 2000). استخدم شكل trip المفكوك من /routing/plan. |
costing | string | اختياري — auto (الافتراضي)، truck، bicycle، pedestrian، motor_scooter |
shapeMatch | string | اختياري — walk_or_snap (الافتراضي)، map_snap، edge_walk |
curl -s -X POST "https://navvo.io/api/v1/routing/route-attributes" \
-H "x-api-key: $NAVVO_API_KEY" -H "content-type: application/json" \
-d '{ "shape": [ { "lat": 31.9501, "lon": 35.9101 }, { "lat": 31.9520, "lon": 35.9145 } ] }'
الاستجابة
{
"provider": "navvo-routing", "available": true, "costing": "auto", "count": 2,
"edges": [
{ "speedLimitKph": 60, "typicalSpeedKph": 48, "lengthKm": 0.31, "name": "شارع الملكة رانيا",
"roadClass": "primary", "beginShapeIndex": 0, "endShapeIndex": 4 },
{ "speedLimitKph": null, "typicalSpeedKph": 35, "lengthKm": 0.12, "name": null,
"roadClass": "residential", "beginShapeIndex": 4, "endShapeIndex": 7 }
]
}
| الحقل | النوع | ملاحظات |
|---|---|---|
edges[].speedLimitKph | number | null | الحد القانوني المعلَن بالكم/ساعة — null حيث لا حدّ مُخرَّط |
edges[].typicalSpeedKph | number | null | سرعة القيادة النموذجية على الحافة |
edges[].lengthKm | number | null | طول الحافة |
edges[].name | string | null | اسم الشارع الأساسي |
edges[].roadClass | string | null | motorway، primary، residential، … |
edges[].beginShapeIndex / endShapeIndex | number | أي نقاط شكل مُدخلك تمتد عليها الحافة — استخدمهما لتحديد موضع كل حدّ على طول المسار |
لعرض «الحد هنا هو X»: تتبّع أقرب فهرس شكل للسائق واختر الحافة التي تغطيه. عندما يتعذر الوصول للمحرّك تستلم { "provider": "navvo-routing", "available": false }؛ وأقل من نقطتين صالحتين يعيد 400.
التعليمات الصوتية وإرشاد المسارب
تحمل منعطفات المسار أصلاً كل ما يحتاجه محرّك الإرشاد المنطوق — دون استدعاء إضافي. فإلى جانب instruction، يتضمّن كل منعطف في استجابات /routing/route و/routing/plan:
| الحقل | انطقه… |
|---|---|
verbal_transition_alert_instruction | مبكراً، كتنبيه («بعد 400 متر، انعطف يميناً إلى…») |
verbal_pre_transition_instruction | قُبيل نقطة المنعطف مباشرة |
verbal_post_transition_instruction | بعدها مباشرة («تابع لمسافة كيلومترين») |
verbal_succinct_transition_instruction | كصيغة قصيرة عندما تتلاحق المنعطفات |
تحترم هذه الحقول language في الطلب (وتوطين أسماء الطرق بالإنجليزية في /plan).
أما إرشاد المسارب عند الاقتراب من تقاطع، فاستدعِ GET /junction/lanes?lat=…&lng=… بإحداثية المنعطف القادم (النطاق routing):
{ "source": "navvo-lanes", "available": true, "roadName": "شارع غازي عربيات", "laneCount": 2,
"lanes": [ { "indications": ["left"] }, { "indications": ["through", "right"] } ] }
مصفوفة lanes مرتّبة من اليسار إلى اليمين؛ وindications لكل مسرب تسرد انعطافاته المسموحة (فارغة عندما لا يُعرف إلا عدد المسارب). وavailable: false تعني أنه لا بيانات مسارب مُخرَّطة هناك — أخفِ شريط المسارب. النتائج مخزّنة من جهة الخادم، فالاستعلام لكل منعطف زهيد الكلفة.
POST /routing/optimize
ترتيب أمثل للمحطات (بأسلوب مسألة البائع المتجوّل TSP). يُوكِّل إلى optimized_route في محرّك التوجيه. يُعامَل الموقعان الأول والأخير على أنهما بداية/نهاية ثابتتان.
جسم الطلب
{ "payload": <raw routing-engine optimized_route request> } — locations ({lat, lon})، costing، directions_options.
{
"payload": {
"locations": [
{ "lat": 31.95, "lon": 35.91 },
{ "lat": 31.99, "lon": 35.95 },
{ "lat": 31.97, "lon": 35.88 },
{ "lat": 31.93, "lon": 35.90 }
],
"costing": "auto"
}
}
الاستجابة (201)
يُطابق data.trip.locations[].original_index الترتيب الأمثل مع ترتيب إدخالك؛ والباقي رحلة قياسية.
الملخّص
| نقطة النهاية | عملية المحرّك | الجسم | الإحداثيات | إضافات Navvo |
|---|---|---|---|---|
POST /routing/route | route | { payload } | {lat, lon} | labels بالذكاء الاصطناعي |
POST /routing/plan | تلقائي | RoutePlanDto من Navvo | كائنات {lon, lat} | تسميات، قيود، لوجستيات |
POST /routing/matrix | matrix | { payload } | {lat, lon} | — |
POST /routing/isochrone | isochrone | { payload } | {lat, lon} | — |
POST /routing/map-match | trace_route | { payload } | {lat, lon} | — |
POST /routing/route-attributes | trace_attributes | { shape, costing?, shapeMatch? } | {lat, lon} | حدود سرعة لكل حافة |
POST /routing/optimize | optimized_route | { payload } | {lat, lon} | — |