المواصفات

تنطبق بضع قواعد شاملة عبر الواجهة البرمجية بأكملها. قراءة هذه الصفحة مرّة واحدة ستوفّر عليك وقت التصحيح لاحقًا.

عنوان URL الأساسي والإصدارات

تُقدَّم جميع نقاط النهاية تحت بادئة مُصدَّرة:

https://navvo.io/api/v1

تُكتَب المسارات في هذا المرجع كاملةً، مثل GET /api/v1/search.

صحّة الخدمة

نقطة النهاية GET /api/v1/health عامّة وغير مُصادَق عليها — لا تحتاج إلى مفتاح واجهة برمجية — لذا يمكنك استقصاؤها مباشرةً من نظام المراقبة الخاص بك أو من فحوص الجاهزية لديك:

{
  "ok": true,
  "strict": false,
  "service": "navvo-api",
  "time": "2026-07-27T14:08:23.552Z",
  "dependencies": { "mysql": true, "redis": true, "routing": true, "nominatim": true },
  "search": { "engine": "navvo-search", "configured": true }
}

• ok يعكس طبقة تخزين البيانات وحدها (قاعدة البيانات والذاكرة المؤقّتة)، فتدهور تبعية اختيارية لا يقلبه إلى false.
• dependencies.routing هو محرّك التوجيه الخاص بـ Navvo، وnominatim هو خلفية الترميز الجغرافي.
• لكلّ فحص تبعية مهلة قدرها ثانيتان؛ والفحص الفاشل أو المتعذّر يُبلَّغ عنه بالقيمة false بدلًا من أن يُطلِق خطأً.
• search.engine يكشف ما إذا كانت /search تُخدَم فعليًا بواسطة فهرس البحث الكامل navvo-search أم بالبحث الاحتياطي المتدهور في قاعدة البيانات fallback الذي يُستخدَم ما دام الفهرس متعذّر الوصول، بينما يبيّن search.configured ما إذا كان فهرس البحث مضبوطًا أصلًا. كانت الإصدارات السابقة تعرض هاتين الحالتين بأسماء مختلفة؛ فحدِّث أيّ أداة مراقبة كانت تطابق القيم القديمة.
• strict يعكس ما إذا كان وضع الصحّة الصارم مُفعَّلًا.

تُصدِر الاستجابة كذلك مفتاحًا مُهمَلًا مرادفًا يعكس القيمة نفسها الموجودة في routing، وهو مُبقًى فقط لتوافق أدوات المراقبة الأقدم؛ لا تعتمد عليه.

صيغة الطلب والاستجابة

• أجسام الطلبات هي JSON (Content-Type: application/json)، باستثناء رفع الملفات.
• الاستجابات هي JSON ما لم تُعِد نقطة النهاية بلاطة أو صورة (بلاطات متجهة، PNG/JPEG، SVG، أو محارف/رموز مصوّرة .pbf) — تلك تعيد نوع المحتوى الثنائي/image/* المناسب.
• تُحذَف حقول الجسم غير المعروفة بصمت. تتحقّق الواجهة البرمجية من أجسام الطلبات وتدرجها في قائمة بيضاء، لذا تُسقَط الخصائص الإضافية التي ترسلها بدلًا من رفضها.
• تعيد معالِجات POST الرمز 201 Created عند النجاح (افتراضيًا في NestJS)، حتى لنقاط النهاية الحسابية فقط مثل التوجيه.

معرّفات الطلبات والأخطاء

تحمل كل استجابة ترويسة x-request-id، ويكرّرها كل جسم خطأ في الحقل requestId. اذكره عند الإبلاغ عن مشكلة — فهو يحدّد الطلب بعينه في سجلّاتنا، فلا يحتاج أحد إلى إعادة إنتاجه انطلاقًا من وصف.

x-request-id: 09de21ef-fa8f-4815-8453-9a19a3132763

تحتفظ أجسام الأخطاء بالشكل الذي تحلّله عملاء الإصدار الأول أصلًا، وتضيف حقلين:

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Place \"ardh-cafe-ard-kafyh-2bd24a\" not found.",
  "code": "NOT_FOUND",
  "requestId": "847c7a9b-a7c8-4b61-b138-d4e6b585626a"
}

الحقول statusCode وerror وmessage لم تتغيّر. أما code فهو معرّف ثابت مقروء آليًا — تفرّع بناءً عليه لا على message، فالأخير نصّ بشري قد تُعاد صياغته. ومن الرموز التي قد ترغب بمعالجتها تحديدًا: UNAUTHENTICATED وNOT_FOUND وVALIDATION_ERROR وQUOTA_EXCEEDED وRATE_LIMITED وDESTINATION_OUT_OF_COVERAGE.

المصادر المتعدّدة (CORS)

تعكس الواجهة البرمجية Origin الطلب، لذا يمكنك استدعاؤها من JavaScript في المتصفّح على أي نطاق — موقع طرف ثالث يضمّن حزمة Navvo Web SDK المُفعَّلة بمفتاح، أو <img> لخريطة ثابتة، أو تطبيق الويب الخاص بك. المصادقة قائمة على الترويسة/الاستعلام (x-api-key، Authorization: Bearer، api_key) وخالية من ملفّات تعريف الارتباط، لذا لا يحمل CORS المفتوح أي خطر سلطة ضمنية. أما تطبيقات الهاتف الأصلية فليست خاضعة لـ CORS المتصفّح إطلاقًا. فضّل إبقاء المفاتيح السرّية على الخادم حيثما أمكن (راجع حدود المعدّل ← أبقِ المفاتيح على الخادم).

يُخفي المتصفّح معظم ترويسات الاستجابة عن النصوص البرمجية القادمة من مصدر آخر ما لم تكشفها الواجهة البرمجية. وتكشف Navvo الترويسات التالية، فتستطيع شيفرتك في المتصفّح قراءتها عبر response.headers.get(…):

• x-request-id
• Retry-After
• X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset
• x-navvo-quota-limit-minute وx-navvo-quota-remaining-minute وx-navvo-quota-limit-day وx-navvo-quota-remaining-day وx-navvo-quota-reset-minute وx-navvo-quota-unlimited

وتشرح صفحة حدود المعدّل ← ترويسات الاستجابة معنى كل ترويسة من ترويسات الحدود.

الإحداثيات

المربّعات الحدّية

تقبل نقاط النهاية التي تصفّي حسب المنطقة معامل الاستعلام bbox على هيئة أربعة أرقام مفصولة بفواصل:

bbox=west,south,east,north      e.g. bbox=35.85,31.90,35.99,31.99

وهذا هو minLng,minLat,maxLng,maxLat. يجب أن يحقّق المربّع الحدّي west < east وsouth < north. تحدّ نقاط نهاية كثيرة من امتداد المربّع الحدّي على جانب الخادم بناءً على zoom لحماية الأداء.

البلاطات ({z}/{x}/{y})

تستخدم نقاط نهاية البلاطات مخطّط الخريطة المنزلقة / XYZ القياسي: z هو مستوى التكبير (الأصل أعلى اليسار، يُقاس y من الشمال). يجب أن تحقّق إحداثيات البلاطة 0 ≤ z ≤ 22 و0 ≤ x,y < 2^z. تقبل بعض مسارات البلاطات لاحقة ملف على {y} (مثل .png، .pbf، .json) تُجرَّد قبل التحليل.

لتحميل المناطق المحدودة بكفاءة، تكشف كثير من طبقات التراكب نقطة نهاية تغطية البلاطات التي تعيد القائمة الدقيقة لعناوين URL للبلاطات التي تغطّي مربّعًا حدّيًا.

التصفيح

نقاط نهاية العرض التي تصفّح تستخدم معاملَي الاستعلام page (يبدأ من 1) وlimit وتعيد غلافًا:

{ "items": [ ], "total": 137, "page": 1, "limit": 50 }

لا يوجد مؤشّر nextPage — قارِن page * limit مع total لمعرفة متى تتوقّف. تنطبق حدود limit الخاصة بكل نقطة نهاية (راجع صفحة المرجع لكل منها).

الوحدات

• المسافات: كيلومترات ما لم تنصّ نقطة النهاية على خلاف ذلك.
• المُدد: ثوانٍ (تتضمّن بعض الاستجابات أيضًا حقل *Minutes مقرّبًا).
• السرعات: كم/ساعة في الاستجابات؛ أما مدخل استيعاب القياسات فيستخدم م/ث.
• الطوابع الزمنية: سلاسل ISO-8601 (بتوقيت UTC)، مثل 2026-06-09T08:30:00.000Z.

التوطين

Navvo ثنائية اللغة. تتضمّن كثير من كائنات الأماكن كلًّا من nameEn وnameAr. وحيث يُقبَل معامل locale، فإن en وar مدعومان.

ذكر المصدر

عند عرض بلاطات خرائط Navvo أو أنماطها أو صور الشوارع أو بيانات مشتقّة منها، أظهِر إسناد Navvo. تحمل استجابات نمط/بلاطة Navvo سلسلة ذكر المصدر (مثل 2026 © Navvo) في حقول attribution / metadata الخاصة بها، وتضبط استجابات الصور sourceAttributionRequired: true (ذكر مصدر صور Navvo إلزامي).

الاستثناء الوحيد هو الصور الجوية: صور نمط الخريطة satellite هي صور مرخّصة من طرف ثالث تُقدَّم من شبكة توصيل المحتوى الخاصة بمزوّدها، لذا يحمل مصدر satellite داخل النمط سلسلة ذكر المصدر Imagery © Esri, Maxar, Earthstar Geographics إلى جانب © Navvo. وعند عرض ذلك النمط يجب إظهار كلتا السلسلتين. راجع بلاطات الخريطة والأنماط ← الإسناد.