Metadata-Version: 2.4
Name: syunity-meteo
Version: 0.1.0
Summary: Open-Meteo client and local data collector optimized for China
Author: shenarder
License-Expression: MIT
Project-URL: Homepage, https://github.com/shenarder/syunity-meteo
Keywords: weather,open-meteo,meteorology,china
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: apache-iotdb<2,>=1.3
Requires-Dist: PyYAML>=6.0
Requires-Dist: syunity-core>=0.1.5
Dynamic: license-file

# syunity-meteo

[中文](README.en.md) | English

`syunity-meteo` collects Open-Meteo data selected for China and stores it in Apache IoTDB through `syunity-core`'s pooled `IotDBManager`.

## Install and start

Install dependencies, choose `active_mode` and update its IoTDB connection values in `config.yaml`, ensure IoTDB is running, then start the local service:

```bash
pip install -e .
python main.py
```

`main.py` imports the global `settings` instance from `settings.py`; its mode, IoTDB connection values, and standalone collection defaults are loaded from `config.yaml`. By default, development mode targets `127.0.0.1:6667` and collects Shanghai.

- **`dev` mode:** Immediately runs the online interfaces, logs every API response and IoTDB write result, and keeps the scheduler running.
- **`prod` mode:** Does not print application-level payloads. It fills historical data once, reads current weather and air quality at minute `00`, `15`, `30`, and `45`, and reads weather, radiation, and marine forecasts at `00:00`, `06:00`, `12:00`, and `18:00`.

- **History:** Imported from 2006 one time in a background worker; online scheduling continues while it runs.
- **Current weather:** Collected at each 15-minute boundary in `prod`.
- **Forecast:** Collected at 00:00, 06:00, 12:00, and 18:00 in `prod`.

When used as a library, `MeteoService` does not log API results or IoTDB writes by default. Pass `log_results=True` to opt in:

```python
service = MeteoService(settings, OpenMeteoClient(), store, log_results=True)
```

## IoTDB schema

All data is in the configured database, defaulting to `root.meteo`. The standalone default city device identifier is `shanghai`.

| Device path | Timestamp | Measurements |
| --- | --- | --- |
| `root.meteo.<city>.location` | Geocoding collection time | City name, coordinates, timezone, country, and administrative area |
| `root.meteo.<city>.history` | Open-Meteo hourly time | `temperature_2m`, `relative_humidity_2m`, `shortwave_radiation`, `precipitation`, `surface_pressure` |
| `root.meteo.<city>.current` | Local collection time | Current weather values plus `observed_at` |
| `root.meteo.<city>.air_quality` | Collection time | `payload` (complete CAMS response JSON) |
| `root.meteo.<city>.forecast` | Collection/issue time | `payload` (complete ECMWF forecast JSON) |
| `root.meteo.<city>.solar_radiation` | Collection/issue time | `payload` (complete ECMWF radiation JSON) |
| `root.meteo.<city>.marine` | Collection/issue time | `payload` (complete ECMWF WAM response JSON) |
| `root.meteo.<city>.metadata` | Mark creation time | `history_loaded` |

Forecast payloads are stored per issue time rather than forecast-valid time. This preserves all four daily forecast versions and avoids overwriting an earlier model run.

## Data models

| Domain | Endpoint | Model |
| --- | --- | --- |
| City resolution | `geocoding-api.../v1/search` | Official Chinese geocoding |
| Current weather | `api.../v1/forecast` | `ecmwf_ifs025` |
| Future forecast | `api.../v1/forecast` | `ecmwf_ifs025` |
| Historical weather | `archive-api.../v1/archive` | `era5_land` |
| Air quality | `air-quality-api.../v1/air-quality` | CAMS default |
| Solar / radiation | `api.../v1/forecast` | `ecmwf_ifs025` |
| Marine waves | `marine-api.../v1/marine` | `ecmwf_wam025` |

## Project layout

```text
main.py                         # Root local startup entry point
config.yaml                     # Editable IoTDB connection configuration
src/syunity_meteo/
  settings.py                   # YAML connection loading and collection schedule
  client.py                     # Open-Meteo API client
  iotdb_store.py                # syunity_core.database.db templates, writes, and queries
  service.py                    # One-time and recurring task scheduling
tests/                          # Standalone readable test functions
```
