open-meteo-era5-cli

CLI tool for retrieving historical hourly weather data using the Open-Meteo ERA5 reanalysis dataset.

The application fetches weather data based on geographic coordinates and date range, prints a formatted summary and preview table in the terminal, and optionally saves results to CSV or JSON.

The project is fully containerized using Docker for reproducibility and portability.

---

Features

• Fetch historical hourly weather data via Open-Meteo API
• Uses ERA5 reanalysis dataset
• Clean CLI interface with default parameters
• Terminal preview in Markdown table format
• Save results to CSV or JSON
• Fully reproducible environment via Docker

---

Project Structure

open-meteo-era5-cli/
├── app/
│ ├── __init__.py
│ ├── main.py
│ ├── client.py
│ ├── formatter.py
│ └── io_utils.py
├── output/
├── requirements.txt
├── Dockerfile
├── README.md
├── LICENSE
└── .gitignore

---

Requirements

• Docker Desktop (or Docker Engine)

---

Quick Start (Recommended)

docker run --rm abannikovgeo/open-meteo-era5-cli:latest

Default values:

• Location: Lithuania, Vilnius, Cathedral Square ("Stebuklas" tile)
• Date: 1989-08-23 (Baltic Way)

---

Run via Docker Hub

docker pull abannikovgeo/open-meteo-era5-cli:latest
docker run --rm abannikovgeo/open-meteo-era5-cli:latest

---

Build Docker Image Locally

docker build -t open-meteo-era5-cli .
docker run --rm open-meteo-era5-cli

---

Run Application

Run with custom parameters

docker run --rm abannikovgeo/open-meteo-era5-cli:latest \
  --latitude 54.6872 \
  --longitude 25.2797 \
  --start-date 2024-01-15 \
  --end-date 2024-01-15

Save Output to Local File

To save results to your local machine, mount the output directory:

docker run --rm -v ${PWD}/output:/weather_app/output \
  abannikovgeo/open-meteo-era5-cli:latest \
  --output output/weather \
  --format csv

Result will be saved as:

output/weather.csv

---

CLI Arguments

Argument	Description	Default Value
--latitude	Latitude of location	54.685338
--longitude	Longitude of location	25.287455
--start-date	Start date (YYYY-MM-DD)	1989-08-23
--end-date	End date (YYYY-MM-DD)	1989-08-23
--timezone	Timezone (use auto for coordinate-based)	auto
--output	Output file path (without extension)	None
--format	Output format (csv or json)	csv
--preview-rows	Number of rows shown in terminal preview	24

Note: Timezone auto is resolved based on geographic coordinates

---

Output

Terminal

• Summary of request
• Markdown-formatted preview table

File output (optional)

• CSV (tabular format)
• JSON (raw API response)

---

Weather Variables

The application retrieves the following hourly weather variables:

Variable	Short Title	Description	Unit
time	time	Timestamp (ISO 8601)	—
temperature_2m	temp	Air temperature at 2 meters	°C
relative_humidity_2m	rh	Relative humidity at 2 meters	%
precipitation	prec	Precipitation amount	mm
wind_speed_10m	wind	Wind speed at 10 meters	km/h
surface_pressure	press	Surface atmospheric pressure	hPa
cloud_cover	cloud	Total cloud cover	%
weather_code	code	Weather condition code (WMO) (reference)	—

All variables are returned with hourly resolution from the ERA5 dataset.

---

Example Terminal Output

Historical weather data retrieved successfully.
Location: 54.727592, 25.256916
Timezone: Europe/Vilnius
Elevation: 94.0 m
Records: 24 hourly rows
Variables:
  - temperature_2m (°C)
  - relative_humidity_2m (%)
  - precipitation (mm)
  - wind_speed_10m (km/h)
  - surface_pressure (hPa)
  - cloud_cover (%)
  - weather_code (wmo code)

Preview of first 24 rows:
| time             | temp | rh | prec | wind | press  | cloud | code |
| ---------------- | ---- | -- | ---- | ---- | ------ | ----- | ---- |
| 1989-08-23T00:00 | 17.2 | 76 | 0.0  | 9.9  | 1002.9 | 95    | 3    |
| 1989-08-23T01:00 | 16.7 | 80 | 0.0  | 10.0 | 1003.2 | 97    | 3    |
| 1989-08-23T02:00 | 16.5 | 82 | 0.0  | 8.9  | 1003.0 | 99    | 3    |
| 1989-08-23T03:00 | 16.2 | 85 | 0.0  | 7.9  | 1003.0 | 98    | 3    |
| 1989-08-23T04:00 | 16.1 | 87 | 0.0  | 6.1  | 1002.9 | 93    | 3    |

---

Data Source

Weather data is provided by Open-Meteo using the ERA5 reanalysis dataset.

• Global coverage from 1940 to present
• Hourly temporal resolution
• 0.25° (~25 km) spatial resolution

The ERA5 dataset is described in:
Zippenfenig et al., 2023 — https://doi.org/10.5281/zenodo.7970650

Data is used under the CC BY 4.0 license.

---

Notes

• Docker Desktop must be running before executing Docker commands
• On Windows, volume mounting paths may differ depending on terminal