wattnet-api 1.0.0

REST API for wattnet

RESTful API

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.

Purpose

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

Architecture

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.

Requirements

• Python ≥ 3.10
• Docker (for containerised deployment)
• A running wattnet-storage backend

Installation

From PyPI

Installs the wattnet-api server and its wattnet-api CLI entrypoint:

pip install wattnet-api

From source

git clone --recurse-submodules https://github.com/wattnet/wattnet-api.git
cd wattnet-api
poetry install

Docker

Pre-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:latest

Run the container:

docker run -p 8000:8000 --env-file config/.env.production ghcr.io/wattnet/wattnet-api:latest

Configuration

The 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

Running the API

With Poetry

wattnet-api

Or directly with Uvicorn:

uvicorn wattnet.api.app:versioned_app --host 0.0.0.0 --port 8000 --reload

With Docker Compose

docker compose up -d

Interactive API Documentation

Once 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 is https://api.wattnet.eu/v1/.

Health check

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/status

Contributing

Contributions are welcome. See CONTRIBUTING.md for environment setup, code style, and how to run the tests.

License

This repository is licensed under the Apache License 2.0.

See the LICENSE file for more details.

Funding and Acknowledgments

This work is funded by the European Union's Horizon Europe research and innovation programme through the GreenDIGIT project, under grant agreement 101131207.

© 2026 Spanish National Research Council (CSIC). All rights reserved.