GET · /api/v1/navigation/directions

واجهة الملاحة

توجيهات من نقطة إلى أخرى مع تعليمات خطوة بخطوة. تُرجع هندسة مسار GeoJSON، وخطوات مع إرشاد الحارات، وحدود السرعة على المسار ومستويات الازدحام. ستة ملفات ملاحة ومسارات متعددة المحطات.

احسب الاتجاهات

احسب مسارًا من نقطة أصل إلى وجهة، ربما عبر محطات وسيطة. حدّد alternates لتلقي حتى 3 مسارات بديلة إلى جانب المسار الرئيسي.

GET/navigation/directions

حساب مسار مع تعليمات خطوة بخطوة

المعاملات

NameTypeDescription
originLatnumberخط عرض نقطة البداية (-90 إلى 90)
originLngnumberخط طول نقطة البداية (-180 إلى 180)
destLatnumberخط عرض الوجهة (-90 إلى 90)
destLngnumberخط طول الوجهة (-180 إلى 180)
profilestring?ملف الملاحة (الافتراضي: driving-traffic)
languagestring?لغة التعليمات: fr أو ar أو en
alternatesnumber?عدد المسارات البديلة، 0–3 (الافتراضي: 2)
stopsstring?أزواج lat,lng مفصولة بفواصل للمحطات (مثل 18.09,-15.97,18.10,-15.98)
skipSpeedLimitsboolean?تجاوز جلب حدود السرعة لاستجابات إعادة توجيه أسرع
avoidTollsboolean?تجنّب الطرق ذات الرسوم (ملفات driving فقط)
avoidUnpavedboolean?تجنّب الطرق غير المعبّدة (ملفات driving فقط)
avoidFerriesboolean?تجنّب العبّارات (ملفات driving فقط)
avoidHighwaysboolean?تجنّب الطرق السريعة (ملفات driving فقط)

ملفات الملاحة

driving

ملاحة بالسيارة بدون حركة سير مباشرة.

driving-traffic

ملاحة بالسيارة مع حركة السير المباشرة. الافتراضي.

walking

مسارات المشي على الأرصفة والممرات.

cycling

مسارات دراجة تفضل الممرات المخصصة.

truck

ملاحة الشاحنات مع احترام قيود الوزن والحجم.

motorcycle

ملاحة الدراجات النارية بقواعد ذات عجلتين.

مثال على الطلب

cURLbash
curl -X GET "https://api.oolelmaps.com/api/v1/navigation/directions?\
originLat=18.0858&\
originLng=-15.9785&\
destLat=18.1012&\
destLng=-15.9507&\
profile=driving-traffic&\
language=fr&\
alternates=2&\
avoidTolls=true" \
  -H "Authorization: Bearer YOUR_API_KEY"
JavaScriptjavascript
const params = new URLSearchParams({
  originLat: "18.0858",
  originLng: "-15.9785",
  destLat: "18.1012",
  destLng: "-15.9507",
  profile: "driving-traffic",
  language: "fr",
  alternates: "2",
  avoidTolls: "true",
});

const response = await fetch(
  `https://api.oolelmaps.com/api/v1/navigation/directions?${params}`,
  { headers: { Authorization: "Bearer YOUR_API_KEY" } },
);

const data = await response.json();
const routes = Array.isArray(data) ? data : [data];

for (const route of routes) {
  console.log(`Distance: ${route.distance}m, duration: ${route.duration}s`);
  for (const step of route.steps) {
    console.log(`${step.instruction} (${step.distance}m, ${step.maneuverType})`);
  }
}
Pythonpython
import requests

response = requests.get(
    "https://api.oolelmaps.com/api/v1/navigation/directions",
    params={
        "originLat": 18.0858,
        "originLng": -15.9785,
        "destLat": 18.1012,
        "destLng": -15.9507,
        "profile": "driving-traffic",
        "language": "fr",
        "alternates": 2,
        "avoidTolls": True,
    },
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)

data = response.json()
routes = data if isinstance(data, list) else [data]
for route in routes:
    print(f"{route['distance']}m / {route['duration']}s")

مسارات متعددة المحطات

مرّر المعامل stops لإدراج محطات وسيطة. التنسيق: أزواج lat,lng مفصولة بفواصل (مثل stops=18.09,-15.97,18.10,-15.98). يمر المسار عبر كل محطة بالترتيب.

cURLbash
curl -X GET "https://api.oolelmaps.com/api/v1/navigation/directions?\
originLat=18.0858&originLng=-15.9785&\
destLat=18.1012&destLng=-15.9507&\
stops=18.0900,-15.9700,18.0950,-15.9600&\
profile=driving" \
  -H "Authorization: Bearer YOUR_API_KEY"

مثال على الاستجابة

[
  {
    "distance": 4379,
    "duration": 338.276,
    "geometry": [
      [-15.946512, 18.092298],
      [-15.948743, 18.089564],
      [-15.950763, 18.091077],
      [-15.951654, 18.091745]
    ],
    "steps": [
      {
        "instruction": "Drive southwest.",
        "distance": 385,
        "duration": 46.218,
        "maneuverType": "start_right",
        "maneuverDirection": "right",
        "maneuverLocation": [-15.946512, 18.092298],
        "name": ""
      },
      {
        "instruction": "Turn right.",
        "distance": 966,
        "duration": 89.419,
        "maneuverType": "right",
        "maneuverDirection": "right",
        "maneuverLocation": [-15.948743, 18.089564],
        "name": ""
      },
      {
        "instruction": "Turn left onto RN1.",
        "distance": 2730,
        "duration": 159.974,
        "maneuverType": "left",
        "maneuverDirection": "left",
        "maneuverLocation": [-15.955915, 18.09493],
        "name": "RN1"
      }
    ],
    "summary": "RN1 → Avenue du Général de Gaulle",
    "maxSpeeds": [
      { "speed": 50 },
      { "speed": 70 }
    ],
    "congestionLevels": [
      "low",
      "moderate",
      "heavy"
    ],
    "pavedRatio": 1
  }
]

ملاحظات الاستخدام

تنسيق الهندسة

هندسة المسار عبارة عن LineString بـ GeoJSON وإحداثيات بترتيب [خط الطول، خط العرض]، جاهزة للعرض مباشرة على MapLibre GL أو Leaflet أو أي مكتبة متوافقة مع GeoJSON.

حقول الخطوات

تتضمن كل خطوة maneuverType (depart, turn, continue, merge, roundabout, fork, arrive) وmaneuverDirection (left, right, straight, slight left/right, sharp left/right, uturn) يمكنك ربطها بأيقوناتك الخاصة. إرشاد الحارات، عند توفره، موجود في مصفوفة lanes للخطوة.

مسارات بديلة

اضبط alternates على عدد صحيح من 0 إلى 3. إذا احتوت الاستجابة على أكثر من مسار، تُعاد كمصفوفة JSON مرتبة من الأسرع إلى الأبطأ. المسار الواحد يُعاد ككائن مفرد.

خيارات التجنّب

تنطبق avoidTolls وavoidUnpaved وavoidFerries وavoidHighways على ملفات driving و driving-traffic فقط. وتُتجاهل في walking و cycling و truck و motorcycle.

حدود السرعة والازدحام

عند التوفر، تتضمن الاستجابة مصفوفة maxSpeeds بحدود السرعة المسموح بها على كل جزء من الهندسة، ومصفوفة congestionLevels بمستويات حركة المرور لكل جزء (low, moderate, heavy, severe).