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

المسارات السياحية والأسيجة الجغرافية والخرائط الثابتة

تحسين الرحلات متعددة المحطات، والأسيجة الجغرافية مع خطافات الويب، وصور الخرائط الثابتة القابلة للتضمين.

المسارات السياحية والأسيجة الجغرافية والخرائط الثابتة

ثلاث لبنات لميزات الموقع المتقدمة. تشغّل المسارات السياحية تخطيط الرحلات بأسلوب Atlas «اسأل الخرائط» — سلِّم Navvo قائمة محطات لتستعيد ترتيب زيارة مُحسَّنًا مع مسافات وأوقات كل مقطع، إضافةً إلى نقاط نهاية موثَّقة لحفظ رحلات المستخدم ومشاركتها وإعادة تحميلها. وتتيح الأسيجة الجغرافية لفرق الأعمال (B2B) تعريف مناطق دائرية أو مضلّعة، وتقييم موقع جهاز مقابلها، وإطلاق خطافات ويب لحظة دخول الجهاز منطقةً أو خروجه منها. وتُصيّر الخرائط الثابتة صورة خريطة جاهزة للتضمين تضعها مباشرةً داخل عنصر <img> — مثالية للبريد الإلكتروني، ومعاينات الروابط، والبطاقات المُصيَّرة من الخادم.

كل شيء يقدِّمه Navvo ويحمل علامته من واجهة برمجية واحدة. لا توجد خدمات خارجية لربطها.

النطاق المطلوب: routing لتخطيط المسارات؛ و**geo** للأسيجة الجغرافية؛ و**tiles** للخرائط الثابتة. تستخدم نقاط نهاية المسارات المحفوظة رمز جلسة المستخدم (انظر أدناه).

الإحداثيات بالدرجات العشرية (lat، lng). المسافات بالكيلومترات (distanceKm) أو بالأمتار (radiusM) حسب التسمية، والمدد بالدقائق. حلقات المضلّعات مصفوفات من أزواج [lng, lat]. تتدرج نقاط النهاية بلطف — طلب تخطيط يتعذّر تحديد مساره يُعيد available:false بدل خطأ.

POST /itinerary/plan

خطِّط رحلة متعددة المحطات. أعطِ Navvo قائمة محطات (مرتبة أو غير مرتبة) لتستعيد ترتيب زيارة مُحسَّنًا مع المسار المُركَّب بينها — مسافات المقاطع وأوقاتها، وإجماليات الرحلة بما فيها مدة المكوث عند كل محطة. هذا هو المحرّك خلف اقتراحات رحلات Atlas «اسأل الخرائط».

عند تمرير 3 محطات أو أكثر، يحسّن Navvo ترتيب الزيارة لتقليل إجمالي التنقّل مع إبقاء المحطتين الأولى والأخيرة ثابتتين (مرساتا البداية والنهاية)؛ وتُعاد ترتيب المحطات الوسطى. أما مع محطتين فيكتفي بتحديد المسار بينهما. أضِف dwellMin لأي محطة لتخصيص وقت يُقضى فيها.

curl -s "https://navvo.io/api/v1/itinerary/plan" \
  -H "x-api-key: nvvo_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "stops": [
      { "name": "Amman Citadel", "lat": 31.9579, "lng": 35.9344, "dwellMin": 60 },
      { "name": "Rainbow Street", "lat": 31.9510, "lng": 35.9302, "dwellMin": 45 },
      { "name": "The Boulevard Abdali", "lat": 31.9707, "lng": 35.9106, "dwellMin": 90 }
    ],
    "costing": "auto"
  }'

النطاق المطلوب: routing

جسم الطلب

stops

array required

المحطات المطلوب زيارتها. محطتان أو أكثر مطلوبتان. كل عنصر كائن محطة (انظر أدناه).

costing

string

ملف التنقّل للمقاطع بين المحطات: auto (افتراضي)، أو bicycle، أو pedestrian.

كل عنصر في stops[]:

lat

number required

خط عرض المحطة.

lng

number required

خط طول المحطة.

name

string

الاسم المعروض للمحطة. يُعاد ضمن النتيجة المرتبة.

placeId

string

معرّف مكان Navvo اختياري، إذا جاءت المحطة من البحث أو الأماكن.

note

string

ملاحظة نصّية حرّة تُنقل إلى الخطة (مثل «حجز غداء 13:00»).

dwellMin

number

الدقائق التي تُقضى عند هذه المحطة. تُجمَع في إجمالي dwellMinutes للرحلة. القيمة الافتراضية 0.

الاستجابة

الحقل	النوع	الوصف
`provider`	string	دائمًا `navvo-itinerary`.
`available`	boolean	`true` عند إمكانية تحديد مسار الرحلة. و`false` إذا لم يوجد مسار بين المحطات.
`orderedStops[]`	array	المحطات بترتيب الزيارة المُحسَّن (الأولى والأخيرة دون تغيير). يحمل كل عنصر حقول المحطة الأصلية.
`legs[]`	array	مقاطع التنقّل بين المحطات المرتبة المتتالية.
`totals`	object	الملخّص على مستوى الرحلة (انظر أدناه).

كل عنصر في legs[]:

الحقل	النوع	الوصف
`from`	number	الفهرس في `orderedStops[]` لبداية المقطع.
`to`	number	الفهرس في `orderedStops[]` لنهاية المقطع.
`distanceKm`	number	مسافة المقطع بالكيلومترات.
`minutes`	number	زمن تنقّل المقطع بالدقائق.

كائن totals:

الحقل	النوع	الوصف
`distanceKm`	number	إجمالي المسافة عبر كل المقاطع.
`travelMinutes`	number	إجمالي زمن التحرّك بين المحطات.
`dwellMinutes`	number	مجموع `dwellMin` لكل المحطات.
`totalMinutes`	number	`travelMinutes + dwellMinutes` — مدة الرحلة من البداية للنهاية.

{
  "provider": "navvo-itinerary",
  "available": true,
  "orderedStops": [
    { "name": "Amman Citadel", "lat": 31.9579, "lng": 35.9344, "dwellMin": 60 },
    { "name": "Rainbow Street", "lat": 31.9510, "lng": 35.9302, "dwellMin": 45 },
    { "name": "The Boulevard Abdali", "lat": 31.9707, "lng": 35.9106, "dwellMin": 90 }
  ],
  "legs": [
    { "from": 0, "to": 1, "distanceKm": 1.2, "minutes": 6 },
    { "from": 1, "to": 2, "distanceKm": 3.8, "minutes": 11 }
  ],
  "totals": {
    "distanceKm": 5.0,
    "travelMinutes": 17,
    "dwellMinutes": 195,
    "totalMinutes": 212
  }
}

يُبقي المُحسِّن محطتيك الأولى والأخيرة في مكانهما، لذا ثبِّت الرحلة بإدراج نقطة البداية كأول محطة والوجهة النهائية (أو الفندق) كآخر محطة. وكل ما بينهما يُعاد ترتيبه لأقصر مسار.

POST /itinerary/auto

بينما يُرتِّب /itinerary/plan محطات اخترتها سلفاً، فإن /itinerary/auto يكتشفها ويختارها: أعطِه نقطة بداية وميزانية وقت و(اختيارياً) اهتماماتك — فيجد الأماكن القريبة، ثم يختار ويُرتِّب أعلى مجموعة قيمةً تناسب وقتك المتاح. يُحَلّ كمسألة توجيه سياحي (orienteering / جمع الجوائز): تتناسب "كلفة التخطّي" لكل مرشّح مع تقييمه، تحت سقف مدّة مسار يساوي ميزانيتك، فتُبقى أفضل المحطات التي تناسب الوقت وتُسقَط البقية. النطاق routing.

الحقل	النوع	ملاحظات
`start`	`{lat,lng}`	مطلوب — حيث يبدأ اليوم
`timeBudgetMin`	number	إجمالي الوقت المتاح بالدقائق (افتراضي 240؛ 30–1440)
`interests`	string	كلمات تصنيف للمطابقة (مثل `["cafe","museum"]`)؛ احذفها للأعلى تقييماً أيّاً كان نوعه
`radiusKm`	number	نطاق البحث من `start` (افتراضي 8؛ أقصى 50)
`dwellMin`	number	دقائق المكوث عند كل محطة (افتراضي 30)
`maxCandidates`	number	عدد النقاط القريبة المرشّحة للنظر فيها (افتراضي 25؛ أقصى 60)
`costing`	string	ملف التنقّل (افتراضي `pedestrian`)

curl -s -X POST "https://navvo.io/api/v1/itinerary/auto" \
  -H "x-api-key: $NAVVO_API_KEY" -H "content-type: application/json" \
  -d '{ "start": {"lat":31.9539,"lng":35.9106}, "timeBudgetMin": 180, "interests": ["cafe","museum"], "dwellMin": 30 }'

{
  "provider": "navvo-itinerary", "available": true,
  "start": { "lat": 31.9539, "lng": 35.9106 },
  "orderedStops": [
    { "order": 1, "placeId": "…", "slug": "…", "name": "…", "category": "cafe", "rating": 4.7, "dwellMin": 30, "lat": 31.95, "lng": 35.91 }
  ],
  "skipped": [ { "name": "…", "rating": 4.1 } ],
  "totals": { "stops": 4, "candidatesConsidered": 25, "travelMinutes": 49, "dwellMinutes": 120, "totalMinutes": 169, "budgetMinutes": 180 }
}

لا تتجاوز الخطة أبداً budgetMinutes (totalMinutes = التنقّل + المكوث ≤ الميزانية). مرِّر orderedStops مباشرةً إلى POST /me/itineraries لحفظها.

المسارات المحفوظة

تتيح هذه النقاط لمستخدم مسجَّل الدخول تخزين رحلاته وتحديثها ومشاركتها وإعادة تحميلها. وبخلاف بقية هذه الوحدة، تعمل على حساب مستخدم، لذا تتطلب رمز جلسة مستخدم (رمز JWT الصادر عند تسجيل دخول المستخدم) لا مجرّد مفتاح API — مرِّره بالصيغة Authorization: Bearer <user-jwt>. والاستثناء الوحيد نقطة المشاركة العامة التي لا تحتاج أي مصادقة.

سيناريو نموذجي: يخطّط المستخدم رحلةً عبر POST /itinerary/plan، ثم يحفظ النتيجة عبر POST /me/itineraries — خزِّن plan المُعاد كي تُفتح الرحلة فورًا. اضبط isPublic:true للحصول على shareSlug يمكنك مشاركته عبر GET /itineraries/{shareSlug}.

GET /me/itineraries

سرد المسارات المحفوظة للمستخدم مسجَّل الدخول.

curl -s "https://navvo.io/api/v1/me/itineraries" \
  -H "Authorization: Bearer <user-jwt>"

النطاق المطلوب: رمز جلسة مستخدم (لا مفتاح API).

الاستجابة

الحقل	النوع	الوصف
`provider`	string	دائمًا `navvo-itinerary`.
`count`	number	عدد المسارات المُعادة.
`itineraries[]`	array	المسارات المحفوظة للمستخدم (انظر شكل العنصر).

{
  "provider": "navvo-itinerary",
  "count": 1,
  "itineraries": [
    {
      "id": "itn_8f21",
      "name": "Amman Day Trip",
      "stops": [
        { "name": "Amman Citadel", "lat": 31.9579, "lng": 35.9344 },
        { "name": "Rainbow Street", "lat": 31.9510, "lng": 35.9302 }
      ],
      "notes": "Start late morning",
      "isPublic": true,
      "shareSlug": "amman-day-trip-8f21",
      "createdAt": "2026-06-20T09:12:00Z",
      "updatedAt": "2026-06-20T09:12:00Z"
    }
  ]
}

POST /me/itineraries

إنشاء مسار محفوظ للمستخدم مسجَّل الدخول.

curl -s "https://navvo.io/api/v1/me/itineraries" \
  -H "Authorization: Bearer <user-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Amman Day Trip",
    "stops": [
      { "name": "Amman Citadel", "lat": 31.9579, "lng": 35.9344, "dwellMin": 60 },
      { "name": "Rainbow Street", "lat": 31.9510, "lng": 35.9302, "dwellMin": 45 }
    ],
    "notes": "Start late morning",
    "isPublic": true
  }'

النطاق المطلوب: رمز جلسة مستخدم (لا مفتاح API).

جسم الطلب

name

string required

الاسم المعروض للمسار.

stops

array required

محطات الرحلة (نفس شكل المحطة في /itinerary/plan).

notes

string

ملاحظات نصّية حرّة للرحلة.

plan

object

نتيجة خطة مُخزَّنة اختيارية (الجسم المُعاد من /itinerary/plan) كي تُفتح الرحلة دون إعادة تحديد المسار.

isPublic

boolean

عند true، يُنشئ Navvo shareSlug كي يمكن عرض الرحلة علنًا. القيمة الافتراضية false.

الاستجابة

الحقل	النوع	الوصف
`provider`	string	دائمًا `navvo-itinerary`.
`id`	string	معرّف المسار الجديد.
`name`	string	اسم المسار.
`stops[]`	array	المحطات المحفوظة.
`notes`	string	الملاحظات المحفوظة، إن وُجدت.
`plan`	object	الخطة المُخزَّنة، إن قُدِّمت واحدة.
`isPublic`	boolean	هل الرحلة قابلة للمشاركة علنًا.
`shareSlug`	string	المُعرِّف العام (يظهر فقط عندما تكون `isPublic` بقيمة `true`).
`createdAt` / `updatedAt`	string	طوابع زمنية بصيغة ISO.

{
  "provider": "navvo-itinerary",
  "id": "itn_8f21",
  "name": "Amman Day Trip",
  "stops": [
    { "name": "Amman Citadel", "lat": 31.9579, "lng": 35.9344, "dwellMin": 60 },
    { "name": "Rainbow Street", "lat": 31.9510, "lng": 35.9302, "dwellMin": 45 }
  ],
  "notes": "Start late morning",
  "isPublic": true,
  "shareSlug": "amman-day-trip-8f21",
  "createdAt": "2026-06-20T09:12:00Z",
  "updatedAt": "2026-06-20T09:12:00Z"
}

POST /me/itineraries/{id}

تحديث مسار محفوظ قائم. أرسل فقط الحقول التي تريد تغييرها؛ وتُقبل نفس حقول جسم POST /me/itineraries.

curl -s "https://navvo.io/api/v1/me/itineraries/itn_8f21" \
  -H "Authorization: Bearer <user-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Amman Day Trip (revised)",
    "isPublic": false
  }'

النطاق المطلوب: رمز جلسة مستخدم (لا مفتاح API).

الاستجابة

تُعيد كائن المسار المُحدَّث (نفس شكل POST /me/itineraries)، مع تحديث updatedAt.

DELETE /me/itineraries/{id}

حذف مسار محفوظ يملكه المستخدم مسجَّل الدخول.

curl -s -X DELETE "https://navvo.io/api/v1/me/itineraries/itn_8f21" \
  -H "Authorization: Bearer <user-jwt>"

النطاق المطلوب: رمز جلسة مستخدم (لا مفتاح API).

الاستجابة

الحقل	النوع	الوصف
`provider`	string	دائمًا `navvo-itinerary`.
`deleted`	boolean	`true` عند إزالة المسار.
`id`	string	المعرّف الذي حُذف.

{
  "provider": "navvo-itinerary",
  "deleted": true,
  "id": "itn_8f21"
}

GET /itineraries/{shareSlug}

جلب مسار مُشارَك علنًا بواسطة shareSlug الخاص به. هذه النقطة عامة — لا تحتاج مفتاح API ولا رمز مستخدم — لذا فهي مثالية لروابط المشاركة وصفحات الرحلات للقراءة فقط. وتكون قابلة للوصول فقط المسارات المحفوظة بـ isPublic:true.

curl -s "https://navvo.io/api/v1/itineraries/amman-day-trip-8f21"

النطاق المطلوب: لا شيء (عام).

الاستجابة

الحقل	النوع	الوصف
`provider`	string	دائمًا `navvo-itinerary`.
`name`	string	اسم المسار.
`stops[]`	array	محطات الرحلة.
`notes`	string	ملاحظات الرحلة، إن وُجدت.
`plan`	object	الخطة المُخزَّنة، إن حُفِظت واحدة.
`shareSlug`	string	المُعرِّف العام.

{
  "provider": "navvo-itinerary",
  "name": "Amman Day Trip",
  "stops": [
    { "name": "Amman Citadel", "lat": 31.9579, "lng": 35.9344, "dwellMin": 60 },
    { "name": "Rainbow Street", "lat": 31.9510, "lng": 35.9302, "dwellMin": 45 }
  ],
  "notes": "Start late morning",
  "plan": {
    "totals": { "distanceKm": 1.2, "travelMinutes": 6, "dwellMinutes": 105, "totalMinutes": 111 }
  },
  "shareSlug": "amman-day-trip-8f21"
}

GET /geofences

سرد الأسيجة الجغرافية، مع ترشيح اختياري لمالك واحد. استخدمه لعرض المناطق التي عرّفها حساب أعمال (B2B) — دوائر ومضلّعات يمكنك رسمها على خريطة أو تمريرها إلى /geofences/evaluate.

curl -s "https://navvo.io/api/v1/geofences?ownerId=fleet-acme" \
  -H "x-api-key: nvvo_YOUR_KEY"

النطاق المطلوب: geo

معاملات الاستعلام

ownerId

string

الترشيح للأسيجة المملوكة لهذا المعرّف (مثل مستأجِر أو أسطول). احذفه لسرد كل الأسيجة المرئية لمفتاحك.

الاستجابة

الحقل	النوع	الوصف
`provider`	string	دائمًا `navvo-geofencing`.
`count`	number	عدد الأسيجة المُعادة.
`geofences[]`	array	الأسيجة الجغرافية (انظر الشكل).

{
  "provider": "navvo-geofencing",
  "count": 1,
  "geofences": [
    {
      "id": "gf_warehouse",
      "name": "Amman Warehouse",
      "shape": "circle",
      "lat": 31.9870,
      "lng": 35.8650,
      "radiusM": 250,
      "webhookUrl": "https://acme.example.com/hooks/navvo",
      "ownerId": "fleet-acme"
    }
  ]
}

POST /geofences

إنشاء سياج جغرافي — منطقة دائرية أو مضلّعة. أرفِق webhookUrl وسيرسل Navvo طلب POST إليه عند انتقالات الدخول/الخروج التي يكتشفها /geofences/evaluate.

curl -s "https://navvo.io/api/v1/geofences" \
  -H "x-api-key: nvvo_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Amman Warehouse",
    "shape": "circle",
    "lat": 31.9870,
    "lng": 35.8650,
    "radiusM": 250,
    "webhookUrl": "https://acme.example.com/hooks/navvo",
    "ownerId": "fleet-acme"
  }'

النطاق المطلوب: geo

جسم الطلب

name

string required

الاسم المعروض للسياج الجغرافي.

shape

string required

نوع الهندسة: circle أو polygon.

lat

number

خط عرض المركز. مطلوب عندما يكون shape بقيمة circle.

lng

number

خط طول المركز. مطلوب عندما يكون shape بقيمة circle.

radiusM

number

نصف قطر الدائرة بالأمتار. مطلوب عندما يكون shape بقيمة circle.

polygon

array

حلقة من أزواج [lng, lat]. مطلوبة عندما يكون shape بقيمة polygon.

webhookUrl

string

الرابط الذي يرسل Navvo طلب POST إليه عند انتقالات الدخول/الخروج (انظر /geofences/evaluate).

ownerId

string

معرّف المالك/المستأجِر المستخدم لتحديد نطاق السياج وترشيحه.

الاستجابة

تُعيد السياج الجغرافي المُنشأ.

الحقل	النوع	الوصف
`provider`	string	دائمًا `navvo-geofencing`.
`id`	string	معرّف السياج الجغرافي الجديد.
`name`	string	اسم السياج الجغرافي.
`shape`	string	`circle` أو `polygon`.
`lat` / `lng` / `radiusM`	number	هندسة الدائرة (تظهر للأسيجة من نوع `circle`).
`polygon`	array	حلقة المضلّع من أزواج `[lng, lat]` (تظهر للأسيجة من نوع `polygon`).
`webhookUrl`	string	هدف خطاف الويب، إن ضُبِط.
`ownerId`	string	معرّف المالك، إن ضُبِط.

{
  "provider": "navvo-geofencing",
  "id": "gf_warehouse",
  "name": "Amman Warehouse",
  "shape": "circle",
  "lat": 31.9870,
  "lng": 35.8650,
  "radiusM": 250,
  "webhookUrl": "https://acme.example.com/hooks/navvo",
  "ownerId": "fleet-acme"
}

لسياج مضلّع، مرِّر "shape": "polygon" مع حلقة polygon بدل lat/lng/radiusM، مثل "polygon": [[35.86,31.98],[35.87,31.98],[35.87,31.99],[35.86,31.99]]. ترتيب الإحداثيات هو [lng, lat].

POST /geofences/evaluate

تقييم موقع جهاز مقابل أسيجتك الجغرافية. يُعيد الأسيجة التي تقع النقطة داخلها الآن — وعند تقديم deviceId — انتقالات الدخول/الخروج منذ آخر رصد لذلك الجهاز. ومع emit:true، يرسل Navvo أيضًا طلب POST إلى webhookUrl لكل سياج تم عبوره.

عند تمرير deviceId و emit معًا، يقارن Navvo الموقع الجديد بآخر حالة مسجَّلة للجهاز لحساب الانتقالات، ويُثبِّت الحالة الجديدة، ويُطلق خطاف ويب لكل سياج تم دخوله أو الخروج منه. وبدون deviceId يُجري فحص نقطة-داخل-سياج عديم الحالة وتكون transitions فارغة.

curl -s "https://navvo.io/api/v1/geofences/evaluate" \
  -H "x-api-key: nvvo_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lat": 31.9869,
    "lng": 35.8651,
    "deviceId": "truck-17",
    "ownerId": "fleet-acme",
    "emit": true
  }'

النطاق المطلوب: geo

جسم الطلب

lat

number required

خط عرض الجهاز الحالي.

lng

number required

خط طول الجهاز الحالي.

deviceId

string

معرّف جهاز ثابت. مطلوب لحساب انتقالات الدخول/الخروج؛ يتذكّر Navvo مجموعة الدخول الأخيرة لهذا الجهاز بين الطلبات.

ownerId

string

حصر التقييم بالأسيجة المملوكة لهذا المعرّف.

emit

boolean

عند true (مع deviceId)، يرسل Navvo طلب POST إلى webhookUrl لكل سياج تم عبوره. القيمة الافتراضية false.

الاستجابة

الحقل	النوع	الوصف
`provider`	string	دائمًا `navvo-geofencing`.
`lat` / `lng`	number	الموقع المُقيَّم (يُعاد كما هو).
`inside[]`	string	معرّفات الأسيجة التي تقع النقطة داخلها حاليًا.
`transitions[]`	array	انتقالات الدخول/الخروج منذ آخر رصد للجهاز (فارغة بدون `deviceId`).

كل عنصر في transitions[]:

الحقل	النوع	الوصف
`geofenceId`	string	السياج الذي تم عبوره.
`type`	string	`enter` (دخول) أو `exit` (خروج).

{
  "provider": "navvo-geofencing",
  "lat": 31.9869,
  "lng": 35.8651,
  "inside": ["gf_warehouse"],
  "transitions": [
    { "geofenceId": "gf_warehouse", "type": "enter" }
  ]
}

حمولة خطاف الويب. عند إطلاق emit، يرسل Navvo طلب POST بصيغة JSON إلى webhookUrl الخاص بالسياج يصف العبور — geofenceId، وtype (enter/exit)، وdeviceId، وlat/lng، وownerId. أعِد 2xx للإقرار؛ ويعيد Navvo المحاولة عند الأعطال العابرة.

POST /geofences/evaluate-batch

افحص نقاطاً كثيرة دفعةً واحدة مقابل كل أسيجتك النشطة في طلب واحد — مثل مواقع أسطول كامل الحيّة. تُحمَّل الأسيجة مرة واحدة وتُختبَر كل نقطة مقابلها، فهو أرخص بكثير من استدعاء /geofences/evaluate لكل مركبة. وهو لقطة بلا حالة (أي الأسيجة التي تقع فيها كل نقطة، إضافةً إلى الإشغال لكل سياج)؛ ولأحداث الدخول/الخروج ذات الحالة استخدم /geofences/evaluate لكل جهاز.

curl -s -X POST "https://navvo.io/api/v1/geofences/evaluate-batch" \
  -H "x-api-key: $NAVVO_API_KEY" -H "content-type: application/json" \
  -d '{ "points": [ {"deviceId":"v1","lat":31.9505,"lng":35.9105}, {"deviceId":"v2","lat":31.97,"lng":35.89} ] }'

الحقل	النوع	ملاحظات
`points`	array	حتى 1000 `{ deviceId?, lat, lng }`
`ownerId`	string	اختياري — حصره بأسيجة مالك واحد (الافتراضي مشروعك)

{
  "provider": "navvo-geofencing", "count": 2, "fencesChecked": 2,
  "occupancy": { "gf_downtown": 1, "gf_shmeisani": 1 },
  "results": [
    { "deviceId": "v1", "lat": 31.9505, "lng": 35.9105, "inside": ["gf_downtown"], "insideNamed": [ { "id": "gf_downtown", "name": "Downtown circle" } ] },
    { "deviceId": "v2", "lat": 31.97, "lng": 35.89, "inside": ["gf_shmeisani"], "insideNamed": [ { "id": "gf_shmeisani", "name": "Shmeisani box" } ] }
  ]
}

occupancy خريطة معرّف-سياج ← عدد (كم نقطة لديك تقع في كل سياج) — مفيدة للوحة "المركبات لكل منطقة" حيّة. يعمل مع أسيجة الدائرة والمضلّع.

GET /tiles/static

تصيير صورة خريطة ثابتة قابلة للتضمين. ركِّب خريطة أساس Navvo متمركزة على نقطة عند تكبير معيّن، وضع علامات دبابيس عليها، لتستعيد صورة تضعها مباشرةً في عنصر <img> — دون الحاجة إلى خريطة جافاسكربت. مثالية للـبريد الإلكتروني، ومعاينات الروابط (Open Graph / البطاقات الاجتماعية)، والبطاقات المُصيَّرة من الخادم حيث لا يمكن تشغيل خريطة تفاعلية.

تُعاد الصورة بصيغة SVG (Content-Type: image/svg+xml)، فتبقى واضحة بأي حجم وتُعرَض مباشرةً في متصفح أو <img> أو خاصية CSS background-image.

curl -s "https://navvo.io/api/v1/tiles/static?center=31.9539,35.9106&zoom=13&size=600x400&markers=31.9579,35.9344;31.9510,35.9302&style=standard&api_key=nvvo_YOUR_KEY" \
  -o map.svg

ضمِّنها مباشرةً في صفحة أو بريد إلكتروني — اضبط api_key في سلسلة الاستعلام لأن عنصر <img> لا يستطيع إرسال ترويسة x-api-key:

<img
  src="https://navvo.io/api/v1/tiles/static?center=31.9539,35.9106&zoom=13&size=600x400&markers=31.9579,35.9344;31.9510,35.9302&style=standard&api_key=nvvo_YOUR_KEY"
  width="600"
  height="400"
  alt="Map of Amman"
/>

النطاق المطلوب: tiles

معاملات الاستعلام

center

string required

مركز الخريطة بالصيغة lat,lng (مثل 31.9539,35.9106).

zoom

number required

مستوى التكبير (تقريبًا 1–19). كلما زاد اقترب العرض.

size

string

حجم الصورة بالبكسل بالصيغة WxH (مثل 600x400). يأخذ حجم بطاقة قياسيًا افتراضيًا؛ ويُقيَّد من جهة الخادم.

markers

string

مواضع دبابيس مفصولة بفاصلة منقوطة، كل منها lat,lng (مثل 31.9579,35.9344;31.9510,35.9302). يصبح كل موضع دبوس Navvo على الصورة.

style

string

نمط خريطة الأساس: standard (افتراضي)، أو dark، أو satellite، أو terrain.

الاستجابة

صورة خريطة. جسم الاستجابة بصيغة SVG مع Content-Type: image/svg+xml، بحجم معامل size، يُظهر خريطة أساس Navvo متمركزة على center عند zoom مع دبوس لكل عنصر في markers.

لأن عنصر <img> لا يستطيع إرسال ترويسات، مرِّر مفتاحك بالصيغة api_key=nvvo_YOUR_KEY في سلسلة الاستعلام لروابط الخرائط الثابتة — نفس النمط المستخدم في روابط بلاطات الخريطة والأنماط. انظر بلاطات الخريطة والأنماط للتفاصيل.

النقل العام والتنقل الخفيف والوضع دون اتصال

محطات وخطوط النقل العام، ومحطات الدراجات والسكوترات، وتخطيط الرحلات، ومناطق الخريطة للعمل دون اتصال.

الخطط والإعلانات والأساطيل والبيانات

كتالوج خطط الواجهة البرمجية، صلاحيات المستهلكين، المواضع الإعلانية المُروَّجة، مطالبات الأعمال وحملاتها، توصيل الميل الأخير للأساطيل، وترخيص البيانات.