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:

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

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:

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.