Référence API

Cette page s’adresse aux développeurs et opérateurs intégrant les API meridian — les visiteurs quotidiens peuvent l’ignorer. Toutes les routes API sont des handlers Next.js App Router sous src/app/api/. Météo et geocode nécessitent OPENWEATHER_API_KEY. Les routes cron nécessitent Authorization: Bearer CRON_SECRET. Les routes admin nécessitent un cookie de session admin authentifié (meridian_admin_session) après connexion sur /login, sauf ALLOW_DEV_ADMIN_BYPASS en développement.

Query : lat, lon, scope (current|hourly|daily|minutely), trigger optionnel, lang. Renvoie payload météo plus fetchedAt, cacheHit, freshness, source, trigger, tokensUsed. L’en-tête X-Cache reflète la couche cache. Erreurs : 400 invalid params, 404 location not found, 429 rate_limited, 502 upstream_error ou service_unavailable.

Body : { cities: [{ lat, lon, scopes?: string[], id?, lang?, maxAgeMs?, trigger? }], trigger?, lang? }. Renvoie { cities: [{ lat, lon, scopes: { scope: { data, meta } | { error } } }] }. Scopes par ville, pas de tableau de niveau supérieur. Limité à 20 requêtes/minute par IP. Utilisé par les hooks tableau de bord et détail ville.

Query : lat, lon, from, to optionnels (dates ISO), limit. Renvoie { summary, observations, forecasts: { hourly, daily } } depuis weather_observations et weather_forecast_archive.

Query : q (min 2 caractères), paramètres context optionnels. Renvoie tableau normalisé : name, country, state, lat, lon, label. Limite upstream 5 résultats. Mis en cache L2 avec scope geocode. Limité à 60 requêtes/minute par IP.

Sans paramètres. Renvoie { checks, source } où source est popular quand des lignes déclenchées par recherche existent, ou empty quand aucune. Limite par défaut 20 depuis location_weather_checks classées par volume de recherche (triggers search_select et search_preview). L’API n’a pas de repli showcase — l’UI accueil peut quand même montrer des villes populaires de démo quand vide si SHOW_DEMO_POPULAR_SEARCHES est activé. La colonne Près de vous n’utilise pas cette route.

GET ?clientId= — lister les abonnements actifs pour le client. POST — créer { clientId, email, type, cityName?, cityLat?, cityLon?, frequency?, alertOnRain?, alertOnStorm?, alertPrefs? }. PATCH — mettre à jour alertPrefs sur une ligne city_alerts { clientId, id, alertPrefs }. DELETE — body { clientId, cityLat, cityLon, types[] }. Types : newsletter, city_weekly, city_alerts.

Query : token (unsubscribe_token UUID). Désactive l’abonnement et renvoie une confirmation HTML.

Renvoie alerte normalisée : id, senderName, event, start, end, description. Source : scope alert en cache.

GET /api/cron/weekly-digests — envoyer les e-mails récapitulatifs hebdomadaires groupés par e-mail abonné. GET /api/cron/weather-alerts — évaluer alertPrefs contre OpenWeather, Open-Meteo et flux NWS et envoyer les e-mails d’alerte. Les deux nécessitent Bearer CRON_SECRET.

Usage et config : GET /api/admin/usage ; GET|PATCH /api/admin/config ; legacy PATCH /api/admin/settings { refreshIntervalMs }. Utilisateurs et auth : GET|POST /api/admin/users ; POST /api/admin/users/invite ; GET /api/admin/me. Données : GET /api/admin/checks ; GET /api/admin/locations ; GET|PATCH /api/admin/subscriptions ; GET /api/admin/mailing-summary ; GET /api/admin/analytics. Connecteurs : GET|PATCH /api/admin/connections ; GET|PATCH /api/admin/openweather-key ; GET|PATCH /api/admin/email-key. CMS e-mail : 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. Toutes nécessitent meridian_admin_session sauf contournement dev.

GET /api/ads/config — { scriptEnabled, clientId, consentRequired }. GET /api/ads?placement=dashboard|hero|recent-checks|city-detail — config placement avec slotId si défini. GET /api/ads/placeholder-bg — lookup hero pour surfaces placeholder. Route app GET /ads.txt — ligne éditeur AdSense depuis env. Placements AdSlot actifs : dashboard, hero, city-detail. env slot recent-checks existe mais l’accueil n’a pas d’AdSlot.

GET /api/platform/limits — instantané quota public. POST /api/analytics/collect — beacon analytics first-party. GET /api/location/region — aide IP/région. POST /api/weather/inaccurate-report — signaler de mauvaises données. GET /api/weather/map-tile/[layer]/[z]/[x]/[y] — tuiles overlay hero 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.

Erreurs JSON typiquement { error: code, message: string }. Codes ApiError incluent invalid_request, service_unavailable, location_not_found, rate_limited, upstream_error, unauthorized, not_found, limit_reached.