jardin/prevision meteo/consigne_open_meteo.md

Consigne — Collecte météo Open‑Meteo (Prévisions + Historique)

1. Objectif

Mettre en place une collecte automatique des données Open‑Meteo pour alimenter :

• une vue calendrier météo (agrégat journalier),
• une vue détail horaire.

Le système doit :

• récupérer les prévisions sur horizon configurable (7, 10, 16 jours),
• stocker un cache JSON brut (debug/audit),
• upserter en SQLite sans duplication,
• gérer Europe/Paris sans décalage de date,
• permettre un mode historique (archive) optionnel.

---

2. Source de données

• API prévisions : https://api.open-meteo.com/v1/forecast
• API historique : https://api.open-meteo.com/v1/archive
• Doc : https://open-meteo.com/en/docs

Toujours envoyer :

• timezone=Europe/Paris
• timeformat=iso8601

---

3. Configuration

Créer config.yml (et config.yml.example) :

open_meteo:
  latitude: 45.05
  longitude: 3.48
  timezone: Europe/Paris
  forecast_days: 14
  cache_dir: data/cache
  db_path: data/jardin.db
  wind_strong_kmh: 40

---

4. Requête prévisions (obligatoire)

Variables demandées :

• hourly: temperature_2m,precipitation_probability,precipitation,relative_humidity_2m,wind_speed_10m,wind_direction_10m,cloud_cover,weather_code
• daily: temperature_2m_max,temperature_2m_min,precipitation_sum,precipitation_probability_max,wind_speed_10m_max,sunrise,sunset,weather_code

Exemple :

curl -s "https://api.open-meteo.com/v1/forecast?latitude=45.05&longitude=3.48&hourly=temperature_2m,precipitation_probability,precipitation,relative_humidity_2m,wind_speed_10m,wind_direction_10m,cloud_cover,weather_code&daily=temperature_2m_max,temperature_2m_min,precipitation_sum,precipitation_probability_max,wind_speed_10m_max,sunrise,sunset,weather_code&timezone=Europe/Paris&timeformat=iso8601&forecast_days=14"

Règles :

• forecast_days doit toujours être explicite.
• Lire et logger hourly_units et daily_units.

---

5. Requête archive (optionnelle)

Exemple :

curl -s "https://api.open-meteo.com/v1/archive?latitude=45.05&longitude=3.48&start_date=2026-01-01&end_date=2026-01-31&daily=temperature_2m_max,temperature_2m_min,precipitation_sum&hourly=temperature_2m,precipitation,weather_code&timezone=Europe/Paris&timeformat=iso8601"

Règles :

• exécuter par tranche (mensuelle recommandée),
• source marquée archive.

---

6. Stockage

6.1 Cache JSON brut

Fichiers à écrire à chaque run :

• data/cache/openmeteo_forecast_<YYYY-MM-DDTHHMMSS>.json
• data/cache/openmeteo_archive_<YYYY-MM-DDTHHMMSS>.json (si archive)

Purge :

• conserver les 30 derniers fichiers par type.

6.2 SQLite normalisée

Table meteo_daily :

• date TEXT NOT NULL
• source TEXT NOT NULL (forecast | archive)
• tmin_c REAL
• tmax_c REAL
• precip_mm REAL
• precip_prob_max_pct REAL
• wind_max_kmh REAL
• sunrise_local TEXT
• sunset_local TEXT
• weather_code INTEGER
• fetched_at TEXT NOT NULL
• lat REAL NOT NULL
• lon REAL NOT NULL
• elevation REAL
• PRIMARY KEY (date, source)

Table meteo_hourly :

• datetime_local TEXT NOT NULL (YYYY-MM-DDTHH:MM)
• source TEXT NOT NULL (forecast | archive)
• temp_c REAL
• precip_mm REAL
• precip_prob_pct REAL
• humidity_pct REAL
• wind_kmh REAL
• wind_dir_deg REAL
• cloud_pct REAL
• weather_code INTEGER
• fetched_at TEXT NOT NULL
• lat REAL NOT NULL
• lon REAL NOT NULL
• elevation REAL
• PRIMARY KEY (datetime_local, source)

Index recommandés :

• idx_meteo_daily_date ON meteo_daily(date)
• idx_meteo_hourly_dt ON meteo_hourly(datetime_local)

---

7. Règles d’upsert

• forecast : INSERT ... ON CONFLICT (...) DO UPDATE (les prévisions évoluent).
• archive : INSERT ... ON CONFLICT (...) DO NOTHING (on fige l’observé).

Conflits :

• meteo_daily : (date, source)
• meteo_hourly : (datetime_local, source)

---

8. Contrôles qualité obligatoires

Après récupération JSON :

• daily.time contient au moins 7 jours,
• longueurs cohérentes des tableaux hourly,
• pour chaque jour : tmin_c <= tmax_c,
• présence de timezone == Europe/Paris.

En cas d’échec :

• logger erreur explicite,
• conserver le JSON brut,
• sortie non fatale avec code d’erreur contrôlé.

---

9. Champs attendus pour l’UI

Vue calendrier (jour)

• date
• tmin_c, tmax_c
• precip_mm
• precip_prob_max_pct
• weather_code
• sunrise_local, sunset_local
• badges calculés :
  • gel si tmin_c <= 0
  • pluie si precip_mm > 0
  • vent_fort si wind_max_kmh >= wind_strong_kmh

Vue détail (horaire)

• datetime_local
• temp_c
• precip_prob_pct
• precip_mm
• wind_kmh, wind_dir_deg
• humidity_pct
• cloud_pct
• weather_code

---

10. Livrables

• prevision meteo/scripts/fetch_openmeteo_forecast.py
• prevision meteo/scripts/fetch_openmeteo_archive.py (optionnel)
• prevision meteo/db/schema.sql
• prevision meteo/config.yml.example

---

11. Exécution planifiée

• Prévisions : tous les jours à 06:10 Europe/Paris.
• Archive (optionnel) : tous les jours à 06:20 pour J-1.

Exemple cron :

10 6 * * * /usr/bin/python3 /path/prevision\ meteo/scripts/fetch_openmeteo_forecast.py
20 6 * * * /usr/bin/python3 /path/prevision\ meteo/scripts/fetch_openmeteo_archive.py --yesterday

---

12. Critères d’acceptation

• Une exécution quotidienne met à jour forecast sans duplication.
• Le calendrier UI affiche au minimum : Tmin/Tmax, pluie, probabilité pluie, weather code.
• Le détail horaire est consultable pour un jour donné.
• Les dates/heures sont correctes en Europe/Paris.
• Les caches JSON sont présents et exploitables pour debug.

https://api.open-meteo.com/v1/forecast?latitude=45.1412&longitude=4.0736&hourly=temperature_2m,weather_code,cloud_cover,evapotranspiration,precipitation,precipitation_probability,rain,snowfall,wind_speed_10m,relative_humidity_2m,wind_direction_10m,soil_temperature_0cm,soil_temperature_6cm,soil_moisture_1_to_3cm,soil_moisture_3_to_9cm,sunshine_duration&forecast_days=14