البدء

المواصفات

عنوان URL الأساسي، الإصدارات، ترتيب الإحداثيات، صيغة bbox، البلاطات، التصفيح، وذكر المصدر.

المواصفات

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

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

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

https://navvo.io/api/v1

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

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

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

الإحداثيات

ترتيب الإحداثيات غير موحّد عبر الواجهة البرمجية — فهو يتبع المواصفة الأصلية لكل محرّك أساسي. تحقّق دائمًا من المرجع الخاص بكل نقطة نهاية. يلخّص الجدول أدناه القواعد.

المكان	الصيغة	ملاحظات
مخرجات GeoJSON (طبقات التراكب، خطوط الزمن المتساوي، الحوادث، حركة المرور، الطقس)	`[lng, lat]`	GeoJSON القياسي — خط الطول أولًا.
`center` للمكان / `location` للمدخل	`POINT(lng lat)` (سلسلة WKT)	خط الطول أولًا. حلّل السلسلة بنفسك.
معامل الاستعلام `bbox`	`west,south,east,north`	أي `minLng,minLat,maxLng,maxLat`.
التوجيه — `payload` الخام (route/matrix/إلخ)	كائنات `{ "lat": …, "lon": … }`	الصيغة الأصلية لمحرّك التوجيه — لاحظ `lon`، وليس `lng`.
التوجيه — `/plan`، حركة المرور — `/route`	كائنات `{ "lon": …, "lat": … }`	معرّفة من Navvo؛ المفاتيح مُسمّاة، لذا الترتيب غير مهم.
الترميز الجغرافي العكسي	معاملات الاستعلام `lat` و`lon`	معاملان منفصلان.
Geo ثلاثية الأبعاد — هندسة `way`	`POINT/LINESTRING/POLYGON(x y)` بنظام EPSG:3857	أمتار Web-Mercator، وليست درجات.

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

تقبل نقاط النهاية التي تصفّي حسب المنطقة معامل الاستعلام 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 لحماية الأداء.

تستخدم نقاط نهاية البلاطات مخطّط الخريطة المنزلقة / 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 إلزامي). ولا يلزم أي إسناد لطرف ثالث في تطبيقك.

الأخطاء ورموز الحالة

رموز حالة HTTP، وأشكال استجابات الأخطاء، وغلاف توفّر المحرّك.

بوابة المطوّرين

استخدم بوابة مطوّري Navvo لإنشاء المؤسسات والمشاريع، وإدارة مفاتيح API، ومراقبة الاستخدام الحيّ، وتجربة نقاط النهاية في بيئة الاختبار.