Metadata-Version: 2.4
Name: wetterdienst
Version: 0.133.0
Summary: Open weather data for humans
Keywords: aemet,state-meteorological-agency-of-spain,dmi,danish-meteorological-institute,smhi,swedish-meteorological-and-hydrological-institute,knmi,royal-netherlands-meteorological-institute,deutscher-wetterdienst,dmo,eaufrance-hubeau,environment-and-climate-change-canada,environmental-agency-uk,federal-waterways-and-shipping-administration-germany,forecast,geosphere-austria,ghcn,historical,institute-of-meteorology-and-water-management-poland,meteo-france,synop,federal-office-of-meteorology-and-climatology-switzerland,meteoswiss,mosmix,met-norway,norwegian-meteorological-institute,frost,national-oceanic-and-atmospheric-administration,national-weather-service,royal-meteorological-institute-of-belgium,near-real-time,observation,open-data,open-source,radar,radolan,recent,time-series,weather-api,weather-data,weather-station
Author: Benjamin Gutzmann, Andreas Motl
Author-email: Benjamin Gutzmann <benjamin@eobs.org>, Andreas Motl <andreas.motl@panodata.org>
License-File: LICENSE.md
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Communications
Classifier: Topic :: Database
Classifier: Topic :: Internet
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Human Machine Interfaces
Classifier: Topic :: Scientific/Engineering :: Hydrology
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Interface Engine/Protocol Translator
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Archiving
Classifier: Topic :: Text Processing
Classifier: Topic :: Utilities
Requires-Dist: aiohttp>=3.14.0,<4
Requires-Dist: backports-datetime-fromisoformat>=2 ; python_full_version < '3.11'
Requires-Dist: certifi>=2024.2.2
Requires-Dist: click>=8.2,<9
Requires-Dist: cloup>=3.0.1,<4
Requires-Dist: fsspec[http]>=2024.6
Requires-Dist: lxml>=4.9.1,<7
Requires-Dist: measurement>=3.2,<4
Requires-Dist: platformdirs>=4,<5
Requires-Dist: polars[calamine]>=1.43.0,<2
Requires-Dist: portion>=2.4.2,<3
Requires-Dist: pyarrow>=22.0.0
Requires-Dist: pydantic>=2.7.3,<3
Requires-Dist: pydantic-extra-types>=2.10.1,<3
Requires-Dist: pydantic-settings>=2.7.0,<3
Requires-Dist: python-dateutil>=2.8.2,<3
Requires-Dist: rapidfuzz>=3.1,<4
Requires-Dist: diskcache>=5.6.3,<6
Requires-Dist: stamina>=25.1.0,<27
Requires-Dist: tabulate>=0.9,<1
Requires-Dist: tqdm>=4.64,<5
Requires-Dist: typing-extensions>=4.15.0,<5
Requires-Dist: tzdata>=2024.2
Requires-Dist: tzfpy>=0.15.2,<2
Requires-Dist: pdbufr>=0.10.2,<1 ; extra == 'bufr'
Requires-Dist: pybufrkit>=0.2,<1 ; extra == 'bufr'
Requires-Dist: pandas>=2.2.2,<4 ; extra == 'cratedb'
Requires-Dist: sqlalchemy-cratedb>=0.40,<1 ; extra == 'cratedb'
Requires-Dist: duckdb>=1,<2 ; extra == 'duckdb'
Requires-Dist: pandas>=2.2.2,<4 ; extra == 'duckdb'
Requires-Dist: eccodes>=1.5.2,<3 ; extra == 'eccodes'
Requires-Dist: xlsxwriter>=3.0.9,<4 ; extra == 'excel'
Requires-Dist: pandas>=2.2.2,<4 ; extra == 'export'
Requires-Dist: sqlalchemy>=2,<3 ; extra == 'export'
Requires-Dist: xarray>=2024.6,<2027 ; extra == 'export'
Requires-Dist: xlsxwriter>=3.0.9,<4 ; extra == 'export'
Requires-Dist: zarr>=3.1,<4 ; python_full_version >= '3.11' and extra == 'export'
Requires-Dist: influxdb>=5.3,<6 ; extra == 'influxdb'
Requires-Dist: influxdb-client>=1.18,<2 ; extra == 'influxdb'
Requires-Dist: influxdb3-python>=0.3,<1 ; extra == 'influxdb'
Requires-Dist: scipy>=1.14.1,<2 ; extra == 'interpolation'
Requires-Dist: shapely>=2.0.4,<3 ; extra == 'interpolation'
Requires-Dist: utm>=0.7,<1 ; extra == 'interpolation'
Requires-Dist: h5netcdf>=1.7.3,<2 ; extra == 'knmi'
Requires-Dist: h5py>=3.11,<4 ; extra == 'knmi'
Requires-Dist: wetterdienst[restapi] ; extra == 'mcp'
Requires-Dist: fastmcp>=3.4.4,<4.0.0 ; extra == 'mcp'
Requires-Dist: mysqlclient>=2,<3 ; extra == 'mysql'
Requires-Dist: pandas>=2.2.2,<3 ; extra == 'mysql'
Requires-Dist: pypdf>=3.12.1,<7 ; extra == 'pdf'
Requires-Dist: kaleido>=1.0.0 ; extra == 'plotting'
Requires-Dist: plotly>=6.1.1 ; extra == 'plotting'
Requires-Dist: psycopg2-binary>=2,<3 ; extra == 'postgresql'
Requires-Dist: h5netcdf>=1.7.3 ; extra == 'radar'
Requires-Dist: h5py>=3.11,<4 ; extra == 'radar'
Requires-Dist: tabula>=1.0.5 ; extra == 'radar'
Requires-Dist: pybufrkit>=0.2,<1 ; extra == 'radarplus'
Requires-Dist: wradlib>=2.0.1,<3 ; extra == 'radarplus'
Requires-Dist: xradar>=0.2,<1 ; extra == 'radarplus'
Requires-Dist: fastapi>=0.115,<1 ; extra == 'restapi'
Requires-Dist: httpx>=0.27,<1 ; extra == 'restapi'
Requires-Dist: uvicorn[standard]>=0.30,<1 ; extra == 'restapi'
Requires-Dist: duckdb>=1,<2 ; extra == 'sql'
Requires-Python: >=3.10
Project-URL: Homepage, https://wetterdienst.readthedocs.io/
Project-URL: Issues, https://github.com/earthobservations/wetterdienst/issues
Project-URL: Releases, https://github.com/earthobservations/wetterdienst/releases
Project-URL: Repository, https://github.com/earthobservations/wetterdienst
Project-URL: Restapi, https://wetterdienst.eobs.org/
Provides-Extra: bufr
Provides-Extra: cratedb
Provides-Extra: duckdb
Provides-Extra: eccodes
Provides-Extra: excel
Provides-Extra: export
Provides-Extra: influxdb
Provides-Extra: interpolation
Provides-Extra: knmi
Provides-Extra: mcp
Provides-Extra: mysql
Provides-Extra: pdf
Provides-Extra: plotting
Provides-Extra: postgresql
Provides-Extra: radar
Provides-Extra: radarplus
Provides-Extra: restapi
Provides-Extra: sql
Description-Content-Type: text/markdown

# Wetterdienst - Open weather data for humans

<p align="center">
  <img src="https://raw.githubusercontent.com/earthobservations/wetterdienst/main/docs/assets/hohenpeissenberg_warming_stripes.png" alt="Warming stripes for Hohenpeißenberg, Germany: one stripe per year from 1781 to 2025, blue for cold years and red for warm ones" width="880" height="440"/>
  <br/>
  <em>Hohenpeißenberg, Germany: 245 years of mean air temperature, one stripe per year from 1781 to 2025 — fetched and drawn with wetterdienst.</em>
</p>

<h2 align="center">Global warming is not an opinion.</h2>
<p align="center"><em>Erderwärmung ist keine Meinung.</em></p>

[![CI status](https://github.com/earthobservations/wetterdienst/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/earthobservations/wetterdienst/actions?workflow=Tests)
[![Documentation status](https://readthedocs.org/projects/wetterdienst/badge/?version=latest)](https://wetterdienst.readthedocs.io/en/latest/?badge=latest)
[![Code coverage](https://codecov.io/gh/earthobservations/wetterdienst/branch/main/graph/badge.svg)](https://codecov.io/gh/earthobservations/wetterdienst)
[![PyPI version](https://img.shields.io/pypi/v/wetterdienst.svg)](https://pypi.org/project/wetterdienst/)
[![Conda version](https://img.shields.io/conda/vn/conda-forge/wetterdienst.svg)](https://anaconda.org/conda-forge/wetterdienst)
[![Python version compatibility](https://img.shields.io/pypi/pyversions/wetterdienst.svg)](https://pypi.python.org/pypi/wetterdienst/)
[![Project license](https://img.shields.io/github/license/earthobservations/wetterdienst)](https://github.com/earthobservations/wetterdienst/blob/main/LICENSE)
[![PyPI downloads](https://static.pepy.tech/personalized-badge/wetterdienst?period=month&units=international_system&left_color=grey&right_color=blue&left_text=PyPI%20downloads/month)](https://pepy.tech/project/wetterdienst)
[![Citation reference](https://zenodo.org/badge/DOI/10.5281/zenodo.3960624.svg)](https://doi.org/10.5281/zenodo.3960624)

> [!WARNING]
> This library is a work in progress!
> Breaking changes should be expected until a 1.0 release, so version pinning is recommended.

Wetterdienst gives you weather, climate and hydrology data from 22 national services through one
interface: one way to find a station, one way to ask for values, one shape of result. It is a
[polars](https://www.pola.rs/)-based Python library, a command line client, a REST API, an MCP
endpoint and a web app, all serving the same data.

Contributions and feedback are very welcome — we do not use most of this data ourselves, so what
you need is what tells us what to build next. Hand in an issue or a PR.

## What we support

| Provider                                                                                       | Country       | What you get                                                          |
|------------------------------------------------------------------------------------------------|---------------|-----------------------------------------------------------------------|
| [DWD](https://www.dwd.de/)                                                                     | 🇩🇪 Germany     | observations, MOSMIX/DMO forecasts, radar, warnings, road weather, derived indices |
| [AEMET](https://www.aemet.es/)                                                                 | 🇪🇸 Spain       | observations (API key)                                                |
| [CHMI](https://www.chmi.cz/)                                                                   | 🇨🇿 Czechia     | observations                                                          |
| [DMI](https://www.dmi.dk/)                                                                     | 🇩🇰 Denmark     | observations, incl. Greenland and the Faroe Islands (API key)         |
| [EA](https://environment.data.gov.uk/)                                                         | 🇬🇧 England     | hydrology                                                             |
| [Eaufrance](https://hubeau.eaufrance.fr/)                                                      | 🇫🇷 France      | hydrology                                                             |
| [ECCC](https://climate.weather.gc.ca/)                                                         | 🇨🇦 Canada      | observations                                                          |
| [FMI](https://en.ilmatieteenlaitos.fi/)                                                        | 🇫🇮 Finland     | observations                                                          |
| [GeoSphere](https://www.geosphere.at/)                                                         | 🇦🇹 Austria     | observations                                                          |
| [IMGW](https://www.imgw.pl/)                                                                   | 🇵🇱 Poland      | meteorology, hydrology                                                |
| [IPMA](https://www.ipma.pt/)                                                                   | 🇵🇹 Portugal    | observations                                                          |
| [KNMI](https://www.knmi.nl/)                                                                   | 🇳🇱 Netherlands | observations (API key)                                                |
| [LHMT](https://www.meteo.lt/)                                                                  | 🇱🇹 Lithuania   | observations                                                          |
| [Met Office](https://www.metoffice.gov.uk/)                                                    | 🇬🇧 UK          | MIDAS Open observations (CEDA account)                                |
| [Météo-France](https://meteofrance.com/)                                                       | 🇫🇷 France      | observations, SYNOP                                                   |
| [MeteoSwiss](https://www.meteoswiss.admin.ch/)                                                 | 🇨🇭 Switzerland | observations                                                          |
| [met.no](https://www.met.no/)                                                                  | 🇳🇴 Norway      | Frost observations (API key)                                          |
| [NOAA](https://www.ncei.noaa.gov/)                                                             | 🌍 worldwide   | GHCN daily and hourly, stations across the globe                      |
| [NWS](https://www.weather.gov/)                                                                | 🇺🇸 USA         | observations                                                          |
| [RMI](https://www.meteo.be/)                                                                   | 🇧🇪 Belgium     | observations                                                          |
| [SMHI](https://www.smhi.se/)                                                                   | 🇸🇪 Sweden      | observations                                                          |
| [WSV](https://www.pegelonline.wsv.de/)                                                         | 🇩🇪 Germany     | hydrology (Pegelonline)                                               |

Across those: **514 canonical parameters**, resolutions from **1 minute to annual**, and archives
reaching back centuries where the service keeps them. Every provider is reached the same way, and a
parameter means the same thing whichever service reports it — `temperature_air_mean_2m` is the mean
air temperature at 2 m, converted to the same unit, everywhere.

Licenses and usage requirements differ per provider, so check the
[data](https://wetterdienst.readthedocs.io/en/latest/data/index.html) chapter before you publish
anything built on them. It also lists every dataset and parameter per provider.

## Features

- Stations, values and station history (metadata changes) through one request model
- Find stations by name, id, distance from a point, bounding box or rank
- Request by `parameters`, `periods`, `start_date`, `end_date`; tune the rest through `Settings`
- Unit conversion, interpolation and summarization for a point between stations
- DWD weather alerts (CAP warnings) with GeoJSON geometry, by community or district
- SQL queries over results, export to CSV/JSON/Excel/Parquet/Zarr and to SQLite, PostgreSQL,
  CrateDB, InfluxDB and DuckDB
- Command line client, REST API and a public Docker image
- MCP (Model Context Protocol) endpoint, so LLM agents can query the data as tools
- Web app with map-based explorer, forecasts, climate stripes and a glossary, at
  [wetterdienst.eobs.org](https://wetterdienst.eobs.org/)

## Setup

```bash
pip install wetterdienst           # from PyPI
pip install wetterdienst[export]   # with an extra
pip install git+https://github.com/earthobservations/wetterdienst  # most recent
```

Extras: `bufr`, `cratedb`, `duckdb`, `eccodes`, `excel`, `export`, `influxdb`, `interpolation`,
`knmi`, `mcp`, `mysql`, `pdf`, `plotting`, `postgresql`, `radar`, `radarplus`, `restapi`, `sql`.
Check the installation with `wetterdienst --help`.

Prefer Docker? The image ships with the optional dependencies included:

```bash
docker pull ghcr.io/earthobservations/wetterdienst
docker run -ti ghcr.io/earthobservations/wetterdienst wetterdienst --version
```

See the [Docker](https://wetterdienst.readthedocs.io/en/latest/usage/docker.html) chapter for
running the REST API and the app from the image.

## Example

Daily precipitation for Zinnwald-Georgenfeld, August 2002 — the flood:

```python
from wetterdienst.provider.dwd.observation import DwdObservationRequest

request = DwdObservationRequest(
    parameters=[("daily", "climate_summary", "precipitation_height")],
    start_date="2002-08-11",
    end_date="2002-08-13",
).filter_by_station_id(station_id=(5779,))

stations = request.df
stations.head()
# ┌────────────┬─────────────────┬────────────┬─────────────────────────┬───┬───────────┬────────┬──────────────────────┬─────────┐
# │ resolution ┆ dataset         ┆ station_id ┆ start_date              ┆ … ┆ longitude ┆ height ┆ name                 ┆ state   │
# │ ---        ┆ ---             ┆ ---        ┆ ---                     ┆   ┆ ---       ┆ ---    ┆ ---                  ┆ ---     │
# │ str        ┆ str             ┆ str        ┆ datetime[μs, UTC]       ┆   ┆ f64       ┆ f64    ┆ str                  ┆ str     │
# ╞════════════╪═════════════════╪════════════╪═════════════════════════╪═══╪═══════════╪════════╪══════════════════════╪═════════╡
# │ daily      ┆ climate_summary ┆ 05779      ┆ 1971-01-01 00:00:00 UTC ┆ … ┆ 13.7516   ┆ 877.0  ┆ Zinnwald-Georgenfeld ┆ Sachsen │
# └────────────┴─────────────────┴────────────┴─────────────────────────┴───┴───────────┴────────┴──────────────────────┴─────────┘

values = request.values.all().df
values.head()
# ┌────────────┬────────────┬─────────────────┬──────────────────────┬─────────────────────────┬───────┬─────────┐
# │ station_id ┆ resolution ┆ dataset         ┆ parameter            ┆ date                    ┆ value ┆ quality │
# ╞════════════╪════════════╪═════════════════╪══════════════════════╪═════════════════════════╪═══════╪═════════╡
# │ 05779      ┆ daily      ┆ climate_summary ┆ precipitation_height ┆ 2002-08-11 00:00:00 UTC ┆ 67.9  ┆ 10.0    │
# │ 05779      ┆ daily      ┆ climate_summary ┆ precipitation_height ┆ 2002-08-12 00:00:00 UTC ┆ 312.0 ┆ 10.0    │
# │ 05779      ┆ daily      ┆ climate_summary ┆ precipitation_height ┆ 2002-08-13 00:00:00 UTC ┆ 26.3  ┆ 10.0    │
# └────────────┴────────────┴─────────────────┴──────────────────────┴─────────────────────────┴───────┴─────────┘

values.to_pandas()  # if you would rather have pandas
```

The same thing from the command line:

```bash
wetterdienst stations --provider=dwd --network=observation --parameters=daily/kl --all
wetterdienst values --provider=dwd --network=observation --parameters=daily/kl --station=1048,4411
```

More in [examples](https://github.com/earthobservations/wetterdienst/tree/main/examples) and in the
[usage](https://wetterdienst.readthedocs.io/en/latest/usage/) chapter.

## Links

- App: [wetterdienst.eobs.org](https://wetterdienst.eobs.org/)
- Documentation: [wetterdienst.readthedocs.io](https://wetterdienst.readthedocs.io/)
  ([usage](https://wetterdienst.readthedocs.io/en/latest/usage/),
  [contribution](https://wetterdienst.readthedocs.io/en/latest/contribution/),
  [changelog](https://wetterdienst.readthedocs.io/en/latest/changelog.html))
- [Examples](https://github.com/earthobservations/wetterdienst/tree/main/examples) and
  [benchmarks](https://github.com/earthobservations/wetterdienst/tree/main/benchmarks)

## What we stand for

- 🏳️‍🌈🏳️‍⚧️ We stand with the LGBTQI+ community.
- ✊ No place for Nazis. FCKNZS.
- 🌡️ Global warming is not an opinion.
- 🔓 Weather data belongs to everyone.

## Acknowledgements

We want to acknowledge all environmental agencies which provide their data open and free of charge
first and foremost for the sake of endless research possibilities.

We want to acknowledge all contributors for being part of the improvements to this library that make
it better and better every day.

## Supported by

<p>
  <!-- same height, each at its own aspect ratio: the JetBrains file is a 298x64 wordmark and the
       Anthropic one a 24x24 glyph, so equal width and height would squash the first. -->
  <a href="https://jb.gg/OpenSourceSupport"><img src="https://resources.jetbrains.com/storage/products/company/brand/logos/jetbrains.svg" alt="JetBrains logo" width="224" height="48"/></a>
  &nbsp;&nbsp;&nbsp;
  <a href="https://www.anthropic.com/"><img src="https://cdn.simpleicons.org/anthropic/181818/ffffff" alt="Anthropic logo" width="48" height="48"/></a>
</p>

Special thanks to the kind people at [JetBrains] s.r.o. for a PyCharm licence through their
open-source support programme, and to [Anthropic] for a Claude Max subscription for open-source
maintainers.

[JetBrains]: https://www.jetbrains.com/
[Anthropic]: https://www.anthropic.com/
