البدء

كل ما تحتاجه قبل أول طلب: العناوين، والوصول بمفتاح أو بنطاق، وترتيب الإحداثيات، والأخطاء والحدود.

العناوين

نفس الخادم يخدم كل شيء. احفظ العناوين في إعدادات التطبيق ولا تكتبها في الكود.

الاسم	العنوان	الخدمات
`GEOCODER_URL`	https://<الخادم>/geocoder	البحث، العنوان، روابط Google
`ROUTING_URL`	https://<الخادم>/routing	المسار، المصفوفة، أقرب طريق، الترتيب، الزحمة، الطرق المغلقة
`TILES_URL`	https://<الخادم>/tiles	الخريطة (إن كانت مفعّلة)

الوصول: مفتاح API أو نطاق مسجّل

مفتاح API في الترويسة X-Api-Key: للموبايل والخوادم. يظهر المفتاح مرة واحدة عند إصداره، ولكل مفتاح قائمة الخدمات المسموحة له، وقد يكون له تاريخ انتهاء.
نطاق مسجّل (مثل https://app.example.iq): طلبات المتصفح منه لا تحتاج مفتاحاً. لا تضع مفتاحاً في كود الموقع: سجّل النطاق بدلاً منه.
نطاق مشترك بين عدة مشاريع: يمكن تسجيل نفس النطاق لأكثر من مشروع، وعندها يجب أن يرسل كل طلب منه مفتاح مشروعه في X-Api-Key، وإلا يُرفض بـ 401.
مفتاح يُرسل من متصفح على نطاق ليس لعميله يُرفض بـ 403، فالمفتاح المسرَّب لا يعمل من موقع آخر.
تبديل المفتاح: المفتاح الجديد يعمل فوراً والقديم يبقى مهلة (7 أيام افتراضياً) حتى تحدّث تطبيقاتك. من «مفاتيح API» في بوابة العملاء.

من خادم أو تطبيق

const res = await fetch(`${ROUTING_URL}/route/v1/driving/44.3661,33.3152;44.4009,33.2778?overview=full&geometries=geojson`, {
  headers: { "X-Api-Key": process.env.MASAR_KEY },
});
const { routes, waypoints } = await res.json();

الإحداثيات: أكثر مصدر للأخطاء

المكان	الترتيب	مثال
مسار OSRM (route, table, nearest, trip)	خط الطول أولاً	`44.3661,33.3152;44.4009,33.2778`
البحث والعنوان (Photon)	معاملات بالاسم	`lat=33.3152&lon=44.3661`
كل الردود (GeoJSON)	خط الطول أولاً	`[44.3661, 33.3152]`
Leaflet	خط العرض أولاً	`L.latLng(33.3152, 44.3661)`
MapLibre	خط الطول أولاً	`[44.3661, 33.3152]`

العراق تقريباً بين خطي طول 38.7 و48.7 وخطي عرض 29 و37.4: خط عرض فوق 38 يعني أن الإحداثيات معكوسة.

شكل الأخطاء

أخطاء البوابة بنفس شكل أخطاء المحرك، فتقرأ شكلاً واحداً لكل خدمة. التفاصيل في الأخطاء والحدود.

// المسار والروابط (OSRM)
{ "code": "TooBig", "message": "Number of entries 26 is higher than current maximum (25)" }

// البحث والعنوان (Photon) والخريطة
{ "message": "Parameter 'q' must not be longer than 200 characters." }

البيانات وحداثتها

بيانات المسار تتحدّث أسبوعياً، والبحث شهرياً. data_version في رد المسار هو تاريخ بيانات OpenStreetMap.
الزحمة تقديرية حسب وقت الأسبوع في المدن، ومقاسة من مركبات العملاء حيث توجد.
GET /health بدون مفتاح يعيد الحالة العامة، لصفحة حالة مثلاً.

OpenAPI

عند تفعيلها، /swagger فيها كل المعاملات وأشكال الردود، والملف /swagger/maps/swagger.json يولّد أنواع TypeScript:

npx openapi-typescript https://<الخادم>/swagger/maps/swagger.json -o masar-api.d.ts