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

التوجيه

الاتجاهات ومصفوفات زمن السفر والمناطق المتساوية الزمن ومطابقة الخريطة وتحسين المحطات.

التوجيه

الاتجاهات وتحليل المسارات، مدعومة بمحرّك التوجيه لدى 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"? } (المفاتيح مُسمّاة، لذا لا يهمّ الترتيب).
تُعيد كل نقاط نهاية التوجيه HTTP 201 عند النجاح. تعذّر الوصول إلى محرّك التوجيه لا يُسبّب خطأً — تحصل على 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
object required
طلب مسار خام لمحرّك التوجيه. يُمرَّر حرفياً (ولا تتحقّق Navvo من صحة حقوله). يجب ألا يكون فارغاً.

حقول payload الشائعة: locations (مصفوفة من {lat, lon, type?}costing (auto، pedestrian، bicycle، truck، motor_scooter، bus، taxi، …)، costing_options، directions_options (units: kilometers/miles، languagealternates، 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 تلقائياً، وتُثري النتيجة بتسميات الذكاء الاصطناعي، وتحليل اختياري للقيود باللغة الطبيعية، وتحليل مخاطر مناطق اللوجستيات.

جسم الطلب

locations
array required
مصفوفة من { "lon": number, "lat": number, "name"?: string }. مطلوب 2 على الأقل.
costing
string
واحد من auto (الافتراضي)، pedestrian، bicycle، motor_scooter، truck.
preference
string
fastest أو shortest أو balanced (الافتراضي). يضبط خيارات التكلفة.
avoid
array
أيٌّ من tolls، highways، ferries، unpaved.
avoidReported
boolean
القيمة الافتراضية true. تجاوز إغلاق الحلقة: بلاغات الملاحظات المعرقِلة (طريق مغلق / مفقود / مناورة غير قانونية / خطر) التي أكّدها محرّر (status: ack) والواقعة ضمن ~30م من الممر تُلتَفّ حولها في التوجيه. البلاغات غير المؤكَّدة لا تؤثّر أبداً، والمؤكَّدة تنتهي صلاحيتها تلقائياً بعد 60 يوماً. تُبلِّغ كتلة reportedConstraints في الاستجابة عمّا طُبِّق. اضبطها على false لتجاهلها.
(تعديلات الطرق)
تُطبَّق دائماً (بدون راية): تعديلات الطرق المُنشأة على منصة Navvo — الإغلاقات وقيود الوصول (GET /road-edits/geojson) — الواقعة ضمن ~70م من الممر تُلتَفّ حولها (إغلاقات الخطوط تتحوّل إلى نقاط مُستبعَدة، وإغلاقات المناطق إلى مضلَّعات مُستبعَدة). تُبلِّغ كتلة roadEditConstraints في الاستجابة عمّا طُبِّق.
optimize
boolean
إذا كان true، يعيد ترتيب المحطات الوسيطة لأقصر جولة (optimized_route في محرّك التوجيه). يُستخدم التحسين أيضاً تلقائياً عند تمرير أكثر من موقعين.
constraintsText
string
قيود توصيل نصّية حرة (مثل النوافذ الزمنية). يحلّلها الذكاء الاصطناعي إلى كتلة constraints مُهيكلة.
includeLabels
boolean
القيمة الافتراضية true. اضبطها على false للحصول على استجابة فورية تُعيد هندسة المسار والمسارات البديلة فقط، متجاوزةً تسمية المسار من الذكاء الاصطناعي (التي تضيف ~1–2 ثانية). مُستحسَنة للتطبيقات التفاعلية الحسّاسة لزمن الاستجابة.
language
string
لغة السرد. القيمة الافتراضية en-US. عند ضبطها على الإنجليزية، تُترجَم أيضاً أسماء الطرق في instruction وstreet_names إلى الإنجليزية (name:enint_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) واستلم، حافة بحافة، حد السرعة القانوني والسرعة النموذجية والطول واسم الطريق وفئته — كل ما يحتاجه عميل الملاحة لعرض حد السرعة المتغيّر مع تقدّم السائق.

جسم الطلب

الحقلالنوعملاحظات
shapearrayمطلوب — نقطتان { "lat": …, "lon": … } على الأقل (بحد أقصى 2000). استخدم شكل trip المفكوك من /routing/plan.
costingstringاختياري — auto (الافتراضي)، truck، bicycle، pedestrian، motor_scooter
shapeMatchstringاختياري — 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[].speedLimitKphnumber | nullالحد القانوني المعلَن بالكم/ساعة — null حيث لا حدّ مُخرَّط
edges[].typicalSpeedKphnumber | nullسرعة القيادة النموذجية على الحافة
edges[].lengthKmnumber | nullطول الحافة
edges[].namestring | nullاسم الشارع الأساسي
edges[].roadClassstring | nullmotorway، primary، residential، …
edges[].beginShapeIndex / endShapeIndexnumberأي نقاط شكل مُدخلك تمتد عليها الحافة — استخدمهما لتحديد موضع كل حدّ على طول المسار

لعرض «الحد هنا هو 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/routeroute{ payload }{lat, lon}labels بالذكاء الاصطناعي
POST /routing/planتلقائيRoutePlanDto من Navvoكائنات {lon, lat}تسميات، قيود، لوجستيات
POST /routing/matrixmatrix{ payload }{lat, lon}
POST /routing/isochroneisochrone{ payload }{lat, lon}
POST /routing/map-matchtrace_route{ payload }{lat, lon}
POST /routing/route-attributestrace_attributes{ shape, costing?, shapeMatch? }{lat, lon}حدود سرعة لكل حافة
POST /routing/optimizeoptimized_route{ payload }{lat, lon}
Copyright © 2026