wattnet-api is the public-facing HTTP interface for the Wattnet platform. It exposes real-time, historical, and forecasted data on the carbon and water footprint of electricity consumption across Europe, fully documented with OpenAPI 3.1 and deployable as a Docker container.
Wattnet computes environmental metrics — carbon footprint, water impact, green scores, generation mix — from open electricity market data. wattnet-api makes all of these metrics available over HTTP so that dashboards, research tools, and third-party applications can query them without coupling to Wattnet's internal data pipeline.
The API is organized into five groups of endpoints:
| Group | Prefix | Description |
|---|---|---|
| Zones | /v1/zones |
Metadata and boundaries for supported electricity zones |
| Energy Metrics | /v1/generation, /v1/load, /v1/imports, /v1/exports, /v1/mix |
Electricity generation, consumption, and cross-border flows |
| Environmental Metrics | /v1/footprints, /v1/impacts, /v1/green-score |
Carbon and water footprint, carbon impact, and green score |
| Shares Metrics | /v1/flow-share, /v1/mix-share, /v1/footprint-share, /v1/impact-share |
Fractional attribution of flows, mix, footprint, and impact |
| Factors | /v1/factors |
Emission and consumption factors used in calculations |
For the full system architecture see the wattnet-architecture repository.
wattnet-api is a FastAPI application served by Uvicorn. It reads energy metrics from wattnet-storage and zone/GeoJSON data from wattnet-data. The API is versioned; all current endpoints live under /v1.
- Python ≥ 3.10
- Docker (for containerised deployment)
- A running wattnet-storage backend
Installs the wattnet-api server and its wattnet-api CLI entrypoint:
pip install wattnet-apigit clone --recurse-submodules https://github.com/wattnet/wattnet-api.git
cd wattnet-api
poetry installPre-built images are published to GHCR and DockerHub for linux/amd64 and linux/arm64. Images are tagged by full version, minor, major, and latest.
# Pull from GHCR
docker pull ghcr.io/wattnet/wattnet-api:latest
# Or from DockerHub
docker pull wattnet/wattnet-api:latestRun the container:
docker run -p 8000:8000 --env-file config/.env.production ghcr.io/wattnet/wattnet-api:latestThe server reads settings from environment variables or a .env file. Copy the example and adjust as needed:
cp config/.env.example config/.env.development| Variable | Default | Description |
|---|---|---|
WATTNET_ENV |
development |
Active environment; selects config/.env.<WATTNET_ENV> |
API_HOST |
localhost |
Bind address for the Uvicorn server |
API_PORT |
8000 |
Listening port |
API_DEBUG |
True |
Enable debug mode and verbose logging |
GEOJSON_PATH |
(bundled wattnet-data) | Directory with GeoJSON zone boundary files |
ZONES_FILE_PATH |
(bundled wattnet-data) | Path to the zones YAML file |
CROSSBORDERS_FILE_PATH |
(bundled wattnet-data) | Path to the crossborders YAML file |
LOG_LEVEL |
INFO |
Logging level (DEBUG, INFO, WARNING, …) |
LOG_HANDLERS |
["console"] |
Log outputs: "console" and/or "file" |
LOG_FILE |
./logs/wattnet-api.log |
Log file path (only used when file handler is active) |
STORAGE_DB_URL |
http://localhost:8123 |
URL for the wattnet-storage ClickHouse backend |
ENTSOE_URL |
https://web-api.tp.entsoe.eu/api |
ENTSO-E Transparency Platform API endpoint |
ELEXON_URL |
https://data.elexon.co.uk/bmrs/api/v1 |
ELEXON Balancing Mechanism Reporting Service endpoint |
EPIAS_URL |
https://seffaflik.epias.com.tr/electricity-service/v1 |
EPIAS Electricity Market Transparency Platform endpoint |
wattnet-apiOr directly with Uvicorn:
uvicorn wattnet.api.app:versioned_app --host 0.0.0.0 --port 8000 --reloaddocker run -d \
-p 8000:8000 \
-e WATTNET_API_CLICKHOUSE_HOST=<host> \
ghcr.io/wattnet/wattnet-api:latestOnce the server is running, explore endpoints, parameters, and responses interactively:
| Interface | URL |
|---|---|
| Swagger UI | http://localhost:8000/v1/docs |
| ReDoc | http://localhost:8000/v1/redoc |
| OpenAPI JSON | http://localhost:8000/v1/openapi.json |
The production instance is available at https://api.wattnet.eu/docs.
The API is versioned. The current version is
v1; the base URL ishttps://api.wattnet.eu/v1/.
The /v1/status endpoint reports whether the API and its upstream dependencies (wattnet-storage, ENTSO-E, ELEXON, EPIAS) are reachable. Useful for readiness probes in containerised deployments:
curl http://localhost:8000/v1/statusContributions are welcome. See CONTRIBUTING.md for environment setup, code style, and how to run the tests.
This repository is licensed under the Apache License 2.0.
See the LICENSE file for more details.
This work is funded by the European Union's Horizon Europe research and innovation programme through the GreenDIGIT project, under grant agreement 101131207.
