Navvo
الأدلّة

الاتجاهات وأوقات الوصول الحيّة

توجيه خطوة بخطوة وأوقات وصول تراعي حركة المرور.

الاتجاهات وأوقات الوصول الحيّة

احصل على اتجاهات خطوة بخطوة ووقت وصول يعكس الازدحام الحالي. يستخدم التوجيه للهندسة وPOST /traffic/route لوقت الوصول المُعدّل وفق حركة المرور.

النطاقات المطلوبة: routingtraffic لأوقات الوصول الحيّة).

الاتجاهات الأساسية

يعمل POST /routing/route على محرّك التوجيه الخاص بـ Navvo. تستخدم المواقع الصيغة الأصلية لمحرّك التوجيه { lat, lon }:

const res = await fetch("https://navvo.io/api/v1/routing/route", {
  method: "POST",
  headers: { "x-api-key": KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    payload: {
      locations: [
        { lat: 31.9539, lon: 35.9106 },
        { lat: 31.9921, lon: 35.9505 },
      ],
      costing: "auto",
      directions_options: { units: "kilometers", language: "en-US" },
    },
  }),
});
const out = await res.json();
if (!out.available) throw new Error("Routing engine unavailable");

const trip = out.data.trip;
console.log(trip.summary.length, "km,", trip.summary.time, "s");
const steps = trip.legs[0].maneuvers.map((m) => m.instruction);
الاستجابة عبارة عن غلاف — تحقّق من available قبل قراءة data. إنّ trip.legs[].shape هو خط متعدّد مُرمّز (دقّة 1e6)؛ فكّ ترميزه لرسم المسار على الخريطة. تُعيد جميع نقاط نهاية التوجيه HTTP 201 عند النجاح.

وقت وصول يراعي حركة المرور

للحصول على وقت وصول مُعدّل وفق حركة المرور الحيّة المصدرة من Navvo، استخدم POST /traffic/route. يستخدم جسم طلب أكثر ودّيةً { lon, lat } ويُعيد مقاطع ملوّنة جاهزة للعرض:

const res = await fetch("https://navvo.io/api/v1/traffic/route", {
  method: "POST",
  headers: { "x-api-key": KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    locations: [
      { lon: 35.9106, lat: 31.9539 },
      { lon: 35.9505, lat: 31.9921 },
    ],
    costing: "auto",
    departureTime: new Date().toISOString(),
  }),
});
const r = await res.json();

console.log("Free-flow:", r.baseDurationSeconds, "s");
console.log("With traffic:", r.durationInTrafficSeconds, "s");
console.log("Delay:", r.delaySeconds, "s");
console.log("Arrival:", r.arrivalTime);

إنّ r.segments هو FeatureCollection بصيغة GeoJSON ملوّن وفق الازدحام — أضفه مباشرةً إلى Navvo Maps:

map.addSource("route", { type: "geojson", data: r.segments });
map.addLayer({
  id: "route",
  type: "line",
  source: "route",
  paint: { "line-color": ["get", "color"], "line-width": 6 },
});

التوجيه إلى مدخل مكان

عند التوجيه إلى مكان في Navvo، استخدم مدخله المُوصى به بدلًا من علامة المركز:

const place = await (await fetch(`https://navvo.io/api/v1/places/${slug}`, { headers: { "x-api-key": KEY } })).json();
const dest = place.arrivalIntelligence.candidates[0].routeTarget; // { lat, lng }

// traffic-aware route to the entrance:
const body = { locations: [origin, { lon: dest.lng, lat: dest.lat }], costing: "auto" };

مصفوفة أوقات السفر

لمقارنة العديد من نقاط الانطلاق/الوجهات دفعةً واحدةً (مثل أقرب سائق)، استخدم POST /routing/matrix بدلًا من N استدعاءً للمسار — فهو طلب واحد وألطف بكثير على حصّتك.

const res = await fetch("https://navvo.io/api/v1/routing/matrix", {
  method: "POST",
  headers: { "x-api-key": KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    payload: {
      sources: [{ lat: 31.95, lon: 35.91 }, { lat: 31.99, lon: 35.95 }],
      targets: [{ lat: 31.90, lon: 35.93 }],
      costing: "auto",
    },
  }),
});
// out.data.sources_to_targets[i][j] -> { time (s), distance (km) }
هل تحتاج إلى قيود بلغة طبيعية ("التوصيل قبل 11:00، وتجنّب وسط المدينة") أو تحسين متعدّد المحطّات؟ استخدم POST /routing/plan — فهو يبني الطلب، ويحسّن ترتيب المحطّات، ويُعيد القيود المُحلّلة بالذكاء الاصطناعي بالإضافة إلى مخاطر منطقة الخدمات اللوجستية.
Copyright © 2026