مرجع واجهة برمجة التطبيقات

هذه الصفحة للمطورين والمشغّلين الذين يدمجون APIs meridian — الزوار العاديون يمكنهم تخطيها. كل مسارات API هي معالجات Next.js App Router تحت src/app/api/. الطقس وgeocode يحتاجان OPENWEATHER_API_KEY. مسارات cron تحتاج Authorization: Bearer CRON_SECRET. مسارات الإدارة تحتاج cookie جلسة إدارة مصادق (meridian_admin_session) بعد /login، ما لم ينطبق ALLOW_DEV_ADMIN_BYPASS في التطوير.

Query: lat، lon، scope (current|hourly|daily|minutely)، trigger اختياري، lang. يعيد حمولة طقس مع fetchedAt وcacheHit وfreshness وsource وtrigger وtokensUsed. ترويسة X-Cache تعكس طبقة الذاكرة. أخطاء: 400 invalid params، 404 location not found، 429 rate_limited، 502 upstream_error أو service_unavailable.

Body: { cities: [{ lat, lon, scopes?: string[], id?, lang?, maxAgeMs?, trigger? }], trigger?, lang? }. يعيد { cities: [{ lat, lon, scopes: { scope: { data, meta } | { error } } }] }. النطاقات لكل مدينة، وليس مصفوفة عليا. محدود بـ 20 طلب/دقيقة لكل IP. يستخدمه hooks لوحة التحكم وتفاصيل المدينة.

Query: lat، lon، from وto اختياريان (تواريخ ISO)، limit. يعيد { summary, observations, forecasts: { hourly, daily } } من weather_observations وweather_forecast_archive.

Query: q (حد أدنى حرفان)، معاملات context اختيارية. يعيد مصفوفة منظمة: name، country، state، lat، lon، label. حد upstream 5 نتائج. مخزّن في L2 بنطاق geocode. محدود بـ 60 طلب/دقيقة لكل IP.

بلا معاملات. يعيد { checks, source } حيث source هو popular عند وجود صفوف مُشغَّلة بالبحث، أو empty عند عدم وجودها. حد افتراضي 20 من location_weather_checks مرتبة بحجم البحث (triggers search_select وsearch_preview). الـ API بلا بديل showcase — واجهة الصفحة الرئيسية قد تعرض مدنًا شائعة تجريبية عند الفراغ إن كان SHOW_DEMO_POPULAR_SEARCHES مفعّلًا. عمود بالقرب منك لا يستخدم هذا المسار.

GET ?clientId= — قائمة اشتراكات نشطة للعميل. POST — إنشاء { clientId, email, type, cityName?, cityLat?, cityLon?, frequency?, alertOnRain?, alertOnStorm?, alertPrefs? }. PATCH — تحديث alertPrefs على صف city_alerts { clientId, id, alertPrefs }. DELETE — body { clientId, cityLat, cityLon, types[] }. الأنواع: newsletter، city_weekly، city_alerts.

Query: token (unsubscribe_token UUID). يعطّل الاشتراك ويعيد تأكيد HTML.

يعيد تنبيهًا منظمًا: id، senderName، event، start، end، description. المصدر: نطاق alert المخزّن.

GET /api/cron/weekly-digests — إرسال رسائل الملخص الأسبوعي مجمّعة حسب بريد المشترك. GET /api/cron/weather-alerts — تقييم alertPrefs مقابل OpenWeather وOpen-Meteo وموجزات NWS وإرسال رسائل التنبيه. كلاهما يحتاج Bearer CRON_SECRET.

الاستخدام والإعداد: GET /api/admin/usage؛ GET|PATCH /api/admin/config؛ legacy PATCH /api/admin/settings { refreshIntervalMs }. المستخدمون والمصادقة: GET|POST /api/admin/users؛ POST /api/admin/users/invite؛ GET /api/admin/me. البيانات: GET /api/admin/checks؛ GET /api/admin/locations؛ GET|PATCH /api/admin/subscriptions؛ GET /api/admin/mailing-summary؛ GET /api/admin/analytics. الموصلات: GET|PATCH /api/admin/connections؛ GET|PATCH /api/admin/openweather-key؛ GET|PATCH /api/admin/email-key. CMS البريد: GET|POST|PATCH /api/admin/email-templates؛ POST /api/admin/email/test، /compose، /sync. AdSense: GET /api/admin/adsense/report؛ POST /api/admin/adsense/sync؛ OAuth GET /api/admin/adsense/oauth/start، /callback، /disconnect. CMS: GET|PATCH /api/admin/cms-pages. الكل يحتاج meridian_admin_session ما لم يكن تجاوز dev.

GET /api/ads/config — { scriptEnabled, clientId, consentRequired }. GET /api/ads?placement=dashboard|hero|recent-checks|city-detail — إعداد موضع مع slotId عند الضبط. GET /api/ads/placeholder-bg — بحث بطل لأسطح العناصر النائبة. مسار التطبيق GET /ads.txt — سطر ناشر AdSense من env. مواضع AdSlot النشطة: dashboard وhero وcity-detail. env فتحة recent-checks موجود لكن الصفحة الرئيسية بلا AdSlot.

GET /api/platform/limits — لقطة حصة عامة. POST /api/analytics/collect — منارة analytics من الطرف الأول. GET /api/location/region — مساعد IP/منطقة. POST /api/weather/inaccurate-report — الإبلاغ عن بيانات سيئة. GET /api/weather/map-tile/[layer]/[z]/[x]/[y] — بلاط overlay بطل OSM. Auth: POST /api/auth/login، /logout؛ POST /api/auth/forgot-password؛ POST /api/auth/reset-password/[token]؛ GET|POST /api/auth/invite/[token]؛ GET /api/auth/session.

أخطاء JSON عادة { error: code, message: string }. رموز ApiError تشمل invalid_request وservice_unavailable وlocation_not_found وrate_limited وupstream_error وunauthorized وnot_found وlimit_reached.