ims_api_documentation.md

# דו"ח משימה 2 – הבאת נתונים מ-IMS (Israel Meteorological Service)

---

## אילו נתונים נלקחים מ-IMS ואיך הם נשמרים

### מקור הנתונים

- **שירות:** IMS (Israel Meteorological Service) – שירות המטאורולוגיה הישראלי.
- **ממשק:** API Envista – `https://api.ims.gov.il/v1/envista/stations/{STATION_ID}/data/{CHANNEL_ID}/?from=YYYY/MM/DD&to=YYYY/MM/DD`
- **תחנה:** **43 – שדה בוקר** (דומה לאקלים ירוחם; מיקום הכרם).
- **אימות:** טוקן API ב־משתנה סביבה `IMS_API_TOKEN` (נשמר מקומית ב־`.env`, לא ב־git).

### ערוצים (Channels) שנלקחים

מזהי הערוצים תלויים בתחנה. **לתחנה 43 (שדה בוקר)** מוגדרים ב־`config/dev.yaml` תחת `ims:`:

| ערוץ IMS (מזהה) | שם IMS | משתנה בפלט (סכמה קנונית) | יחידות | תיאור |
|-----------------|--------|---------------------------|--------|--------|
| 6  | TD   | `air_temperature_c` | °C  | טמפרטורת אוויר נוכחית |
| 8  | TDmax| `tdmax_c`            | °C  | טמפרטורת מקסימום (במהלך המרווח) |
| 9  | TDmin| `tdmin_c`            | °C  | טמפרטורת מינימום (במהלך המרווח) |
| 10 | Grad | `ghi_w_m2`           | W/m²| קרינה גלובלית אופקית (GHI) |

- אם `channel_radiation` מוגדר כ־`null` בתצורה (תחנה ללא Grad), עמודת הקרינה לא נמשכת ומופיעה רק טמפרטורה.

### טווח זמן ורזולוציה

- **טווח ברירת מחדל:** שנתיים אחורה מתאריך ההרצה (ניתן לשנות עם `--from`, `--to` או `--years`).
- **רזולוציה:** נתוני IMS בתדירות 10 דקות; נשמרים כפי שהתקבלו (לא מצוננים).
- **בקשות:** טווח של יותר מ־60 יום מפוצל לחלקים (chunks) כדי למנוע תגובות ריקות מה־API; בין בקשות יש השהייה קצרה.

### עיבוד לפני שמירה

1. **המרת זמן:** חותמות הזמן מגיעות מ־IMS בזמן ישראל (UTC+2/UTC+3). כל התאריכים מומרים ל־**UTC** לפני שמירה.
2. **מיזוג ערוצים:** כל ערוץ נמשך בנפרד; השורות ממוזגות לפי `timestamp_utc` (איחוד אינדקסים – חסרים מסומנים כ־NaN).
3. **סינון טמפרטורה:** ערכים מחוץ לטווח **־50 עד 60 °C** (למשל ערוץ Time hhmm שנדבק בטעות) מוחלפים ב־NaN.
4. **מקור:** נוספת עמודה `source` עם הערך `ims`.

### איפה ואיך נשמרים הנתונים

| פריט | ערך |
|------|-----|
| **קובץ פלט** | `data/ims_radiation_temperature.csv` (נתיב: `config.data_paths.IMS_RADIATION_TEMPERATURE_CSV`) |
| **פורמט** | CSV (פסיק כמפריד) |
| **קידוד** | ברירת מחדל של pandas (בדרך כלל UTF-8) |

**עמודות בקובץ:**

| עמודה | תיאור | יחידות |
|--------|--------|--------|
| `timestamp_utc` | חותמת זמן (UTC) | ISO format, timezone-aware UTC |
| `air_temperature_c` | טמפרטורת אוויר | °C |
| `tdmax_c` | טמפרטורה מקסימלית | °C |
| `tdmin_c` | טמפרטורה מינימלית | °C |
| `ghi_w_m2` | קרינה גלובלית אופקית (Grad) | W/m² |
| `source` | מקור הנתון | תמיד `ims` |

- עמודות שלא נמשכו (למשל קרינה אם אין ערוץ Grad) לא יופיעו או יהיו ריקות.
- שורות עם NaN בחלק מהעמודות אפשריות (למשל אי־התאמה בזמנים בין ערוצים).

### שימוש בנתונים בפרויקט

- הקובץ משמש כ־**מקור מטאורולוגיה (IMS)** ל־**Ground Truth** (משימה 1 – Data fusion).
- סקריפטים נוספים: `scripts/gap_fill_future.py` ממלא פערים (כולל עתיד) ויכול לכתוב ל־`data/ims_radiation_temperature_gap_filled.csv`; `scripts/build_ground_truth.py` ממיר/ממזג ל־Ground Truth (Parquet) לפי הסכמה ב־`context/05_ground_truth_schema.md`.

### ארגון הנתונים (ת pipeline)

סדר העבודה לפי התיעוד:

1. **הורדת IMS (גולמי)**  
   `python -m scripts.download_ims_data`  
   → פלט: `data/ims_radiation_temperature.csv` (רזולוציה 10 דקות, UTC, סינון טמפרטורה -50..60 °C).

2. **השלמת פערים (כולל עתיד)**  
   `python -m scripts.gap_fill_future --input data/ims_radiation_temperature.csv`  
   → פלט: `data/ims_radiation_temperature_gap_filled.csv` (רשת רגולרית, quality_flag).

3. **בניית Ground Truth (Parquet)**  
   `python -m scripts.build_ground_truth`  
   → פלט: `data/ground_truth/ground_truth_2024_2025.parquet` + `ground_truth_metadata.json` (רזולוציה 15 דקות).

הרצת כל הצעדים ברצף (אם קיים קובץ גולמי):

```bash
python -m scripts.download_ims_data && \
python -m scripts.gap_fill_future --input data/ims_radiation_temperature.csv && \
python -m scripts.build_ground_truth
```

או עדכון אוטומטי (כולל TB/DB): `python -m scripts.update_ground_truth`.

---

## נספח – פקודות API (מקור: השירות המטאורולוגי)

תיעוד זה מבוסס על המסמך הרשמי **"ממשק עבור מאגר הנתונים המטאורולוגיים העשר דקתיים"** – משרד התחבורה, השירות המטאורולוגי (תאריך עדכון 11.05.2017). מקור: קובץ "פקודות API" מהשמ"ט. כ־85 תחנות אוטומטיות; הנתונים נמשכים בפורמט JSON.

### אימות (Authorization)

- **שיטה:** `Authorization: ApiToken XXXX`
- **קבלת TOKEN:** פנייה במייל ל־**ims@ims.gov.il**
- בפרויקט: משתנה סביבה `IMS_API_TOKEN` (נשמר ב־`.env`).

### מוסכמת זמן

- **כל השנה לפי זמן מקומי תקני (LST)** – שעון חורף.
- בתקופת שעון קיץ יש הפרש של שעה בין `datetime` המוצג לזמן בפועל (למשל אוקטובר: 11:40+03:00 מוצג בעוד שבפועל 12:40).
- בסקריפט שלנו: כל חותמות הזמן מומרות ל־**UTC** לפני שמירה.

### מטה־דאטה: תחנות ואזורים

מזהי מק placeholders: `{%ST_ID%}` = מספר תחנה, `{%REG_ID%}` = מספר אזור, `{%CH_ID%}` = מספר ערוץ. תאריך: `YYYY/MM/DD`, `MM` = חודש (למשל 05), `DD` = יום (למשל 28).

**תחנות:**

| תיאור | כתובת |
|--------|--------|
| מידע על כל התחנות | `https://api.ims.gov.il/v1/envista/stations` |
| מידע על תחנה ספציפית | `https://api.ims.gov.il/v1/envista/stations/{%ST_ID%}` |

תגובת תחנה כוללת: `name`, `location`, `regionId`, `monitors` (רשימת ערוצים). לכל ערוץ: `active`, `channelId`, `name`, `typeId`, `units`.

**אזורים:**

| תיאור | כתובת |
|--------|--------|
| מידע על כל האזורים (כולל תחנות) | `https://api.ims.gov.il/v1/envista/regions` |
| מידע על אזור ספציפי | `https://api.ims.gov.il/v1/envista/regions/{%REG_ID%}` |

אזור כולל: מספר אזור, שם, רשימת תחנות והערוצים שלהן.

### משיכת נתונים מטאורולוגיים מתחנה

בסיס: `https://api.ims.gov.il/v1/envista/stations/{%ST_ID%}/data/...`

**נתונים אחרונים / ישנים ביותר:**

| תיאור | כתובת |
|--------|--------|
| אחרונים – כל הערוצים | `.../stations/{%ST_ID%}/data/latest` |
| אחרונים – ערוץ ספציפי | `.../stations/{%ST_ID%}/data/{%CH_ID%}/latest` |
| ישנים ביותר – כל הערוצים | `.../stations/{%ST_ID%}/data/earliest` |
| ישנים ביותר – ערוץ ספציפי | `.../stations/{%ST_ID%}/data/{%CH_ID%}/earliest` |

**היום / החודש הנוכחי:**

| תיאור | כתובת |
|--------|--------|
| נתונים מהיום – כל הערוצים | `.../stations/{%ST_ID%}/data/daily` |
| נתונים מהיום – ערוץ ספציפי | `.../stations/{%ST_ID%}/data/{%CH_ID%}/daily` |
| נתונים מהחודש – כל הערוצים | `.../stations/{%ST_ID%}/data/monthly` |
| נתונים מהחודש – ערוץ ספציפי | `.../stations/{%ST_ID%}/data/{%CH_ID%}/monthly` |

**יום / חודש מסוים:**

| תיאור | כתובת |
|--------|--------|
| יום מסוים – כל הערוצים | `.../stations/{%ST_ID%}/data/daily/YYYY/MM/DD` |
| יום מסוים – ערוץ ספציפי | `.../stations/{%ST_ID%}/data/daily/{%CH_ID%}/YYYY/MM/DD` |
| חודש מסוים – כל הערוצים | `.../stations/{%ST_ID%}/data/monthly/YYYY/MM` |
| חודש מסוים – ערוץ ספציפי | `.../stations/{%ST_ID%}/data/{%CH_ID%}/monthly/YYYY/MM` |

**טווח תאריכים (זה מה שהסקריפט משתמש בו):**

| תיאור | כתובת |
|--------|--------|
| טווח – כל הערוצים | `.../stations/{%ST_ID%}/data?from=YYYY/MM/DD&to=YYYY/MM/DD` |
| טווח – ערוץ ספציפי | `.../stations/{%ST_ID%}/data/{%CH_ID%}?from=YYYY/MM/DD&to=YYYY/MM/DD` |

### מבנה תגובת נתונים

- **מספר התחנה**
- **זמן המדידה** (`datetime`)
- **רשימת ערוצים**, לכל ערוץ:
  - `id` – מס' ערוץ
  - `name` – שם הערוץ
  - `status` – **1** = תקין, **2** = לא תקין (כאשר Status=2 הנתונים לא תקינים)
  - `valid` – `true` / `false`
  - ערך מספרי של הפרמטר הנמדד

**הערה:** לא כל התחנות מודדות את כל המשתנים; **מס' הערוץ לאותו משתנה יכול להיות שונה מתחנה לתחנה**. כדי לדעת את מס' הערוץ – להריץ מטה־דאטה על התחנה (או `--list-stations` בסקריפט).

### רשימת משתנים מטאורולוגיים (CHANNEL) – נספח ג'

משתנים שהתחנות עשויות למדוד (שם הערוץ ב-API, יחידות, תיאור):

| משתנה | יחידות | תיאור |
|--------|--------|--------|
| BP   | mb     | לחץ בגובה התחנה |
| DiffR | w/m²  | קרינה מפוזרת |
| Grad  | w/m²  | קרינה גלובלית (GHI) |
| NIP   | w/m²  | קרינה ישירה |
| Rain  | mm    | כמות גשם |
| RH    | %     | לחות יחסית |
| STDwd | deg   | סטיית תקן של כיוון הרוח |
| TD    | degC  | טמפרטורה יבשה (אוויר) |
| TDmax | degC  | טמפרטורת מקסימום |
| TDmin | degC  | טמפרטורת מינימום |
| TG    | degC  | טמפרטורה ליד הקרקע |
| Time  | hhmm  | זמן סיום 10 הדקות המקסימליות |
| WD    | deg   | כיוון הרוח |
| WDmax | deg   | כיוון המשב העליון |
| WS    | m/sec | מהירות הרוח |
| Ws10mm | m/sec | מהירות רוח 10 דקתית מקסימלית |
| WS1mm | m/sec | מהירות רוח דקתית מקסימלית |
| WSmax | m/sec | מהירות המשב העליון |

בפרויקט נמשכים כיום: **TD, TDmax, TDmin, Grad** (תחנה 43 – שדה בוקר). שאר המשתנים (לחץ, גשם, רוח, לחות, קרינה מפוזרת/ישירה וכו') זמינים באותו API לפי מס' ערוץ לכל תחנה.

### שימוש ב-Fiddler (נספח ב')

לבדיקות: כלי חינמי Fiddler. ב-Composer: GET עם הכתובת הרצויה, וב־Header: `Authorization: ApiToken XXXX`.

---

## מה בוצע

### 1. סקריפט הורדת נתונים IMS (`scripts/download_ims_data.py`)

- **מטרה:** הורדת נתונים היסטוריים של קרינה (Grad ≈ GHI) וטמפרטורה (TD, TDmax, TDmin) מ-IMS לשנתיים אחורה.
- **API:** `https://api.ims.gov.il/v1/envista/stations/{STATION_ID}/data/{CHANNEL_ID}/?from=YYYY/MM/DD&to=YYYY/MM/DD`
- **אימות:** טוקן IMS – לבקש מ-ims@ims.gov.il (תנאי שימוש: https://ims.gov.il/en/ObservationDataAPI).
- **משתנה סביבה:** `IMS_API_TOKEN` (או `IMS_TOKEN`) – מומלץ להגדיר ב־`.env`.
- **תצורה:** תחנה וערוצים ב־`config/dev.yaml` תחת `ims:` (ברירת מחדל: תחנה **43 – שדה בוקר**, דומה לירוחם; תחנה 98 = נבטים).
- **פלט:** `data/ims_radiation_temperature.csv` עם עמודות קנוניות: `timestamp_utc`, `air_temperature_c`, `ghi_w_m2`, `tdmax_c`, `tdmin_c`, `source=ims`. חותמות הזמן מומרות מישראל (UTC+2/3) ל-UTC.

**שימוש:**
```bash
# רשימת תחנות (דורש טוקן)
python -m scripts.download_ims_data --list-stations

# הורדה לשנתיים אחורה (ברירת מחדל)
python -m scripts.download_ims_data

# טווח תאריכים ידני
python -m scripts.download_ims_data --from 2024-01-01 --to 2025-12-31 --station 43
```

**הערה:** מזהי הערוצים (channel IDs) תלויים בתחנה; יש לאמת מול ה-API או תיעוד IMS (למשל תחנה 28: TDmax=10, TDmin=11).

---

### 2. סקריפט השלמת פערים לעתיד (`scripts/gap_fill_future.py`)

- **מטרה:** השלמת פערים בעתיד – רשת זמן רגולרית מהתאריך האחרון בנתונים עד תאריך סיום (אופציונלי), עם מילוי פערים ב-forward-fill או אינטרפולציה ליניארית, ואופציה למיזוג עם קובץ תחזית (למשל Open-Meteo).
- **קלט:** קובץ IMS (או כל CSV עם `timestamp_utc` + עמודות מספריות).
- **פלט:** `data/ims_radiation_temperature_gap_filled.csv` עם עמודה `quality_flag`: `observed` | `forward_fill` | `interpolated` | `forecast`.

**שימוש:**
```bash
# השלמת פערים עם forward-fill עד סוף הנתונים
python -m scripts.gap_fill_future --input data/ims_radiation_temperature.csv

# הארכת רשת עד תאריך עתידי
python -m scripts.gap_fill_future --input data/ims_radiation_temperature.csv --end-date 2026-12-31

# מילוי עתיד מתחזית (למשל weather_forecast_cache)
python -m scripts.gap_fill_future --input data/ims_radiation_temperature.csv --forecast data/weather_forecast_cache.csv
```

---

### 3. עדכוני קונפיגורציה

- **`config/data_paths.py`:** נוספו `IMS_RADIATION_TEMPERATURE_CSV`, `IMS_GAP_FILLED_CSV` ו-CSV_SPECS מתאימים.
- **`config/dev.yaml`:** נוסף בלוק `ims:` עם `station_id`, `default_station_id`, ו-channel IDs (ניתן להתאמה לפי תחנה).
- **`config/env.example`:** נוסף `IMS_API_TOKEN` עם הערה לבקשת טוקן.

---

## מה נשאר (אופציונלי)

- **ולידציה:** להריץ הורדה עם טוקן אמיתי ולוודא כיסוי ורזולוציה (שעתי/יומי) מול דרישות Ground Truth.
- **התאמת תחנה/ערוצים:** תחנה 43 = שדה בוקר (דומה לירוחם), תחנה 98 = נבטים. להריץ `--list-stations` לעדכון תחנה/ערוצים.

---

## סיכום

| פריט | סטטוס |
|------|--------|
| תיעוד/גישה ל-IMS API | בוצע – תיעוד וסקריפט |
| סקריפט הורדה (שנתיים אחורה) | בוצע – `download_ims_data.py` |
| מיפוי לסכמה קנונית + CSV | בוצע – `timestamp_utc`, `air_temperature_c`, `ghi_w_m2`, וכו' |
| סקריפט השלמת פערים לעתיד | בוצע – `gap_fill_future.py` |
| ולידציה כיסוי/רזולוציה | ממתין – דורש טוקן IMS והרצה |