veolia-api-foxace 2.4.1

Async client for the Veolia water portals (eau.veolia.fr and delegated portals)

Async Python client for the Veolia water portal API (eau.veolia.fr).

Table of contents

• Installation
• Usage
• Contributing
• Credits
• License

Installation

First of all, you need to install devbox if you don't have a python environment

Once the previous step is done, simply run

devbox shell
cp .env.example .env   # fill in your credentials
python usage_example.py

That's it !

If you already have a python environment just run

pip install veolia-api-foxace

Usage

"""Example of usage of the Veolia API"""

import asyncio
from datetime import date

import aiohttp

from veolia_api.veolia_api import VeoliaAPI


async def main() -> None:
    """Main function."""

    async with aiohttp.ClientSession() as session:
        client_api = VeoliaAPI("[e-mail]", "password", session)

        await client_api.fetch_all_data(date(2025, 1, 1), date(2025, 9, 1))

        # Display fetched data
        print(client_api.account_data.daily_consumption)
        print(client_api.account_data.monthly_consumption)
        print(client_api.account_data.alert_settings.daily_enabled)


if __name__ == "__main__":
    asyncio.run(main())

You can use usage_example.py

Portals

Veolia operates several portals. They share the same Cognito authentication flow but each has its own client_id, and some run on a dedicated data backend. Select a portal with the portal_url argument (defaults to the national portal):

client_api = VeoliaAPI("[e-mail]", "password", session, portal_url="www.ea-pm.fr")

portal_url	Description	Backend
eau.veolia.fr (default)	Veolia France (national)	default
eaudetm.monespace.eau.veolia.fr	Eau de Toulouse Métropole	default
www.ea-pm.fr	Eau de Perpignan Méditerranée Métropole	dedicated

You can resolve a commune name to its portal at setup time:

from veolia_api import resolve_portal_url

portal = await resolve_portal_url("Toulouse")   # "eaudetm.monespace.eau.veolia.fr"
client_api = VeoliaAPI("[e-mail]", "password", session, portal_url=portal)

To add a portal, add an entry to VEOLIA_PORTALS in veolia_api/portals.py with its client_id (found in the portal's JavaScript bundle as ClientId:"...") and, if different from the default, its backend_url.

Maintainers can regenerate the portal table from Veolia's national bundle:

python scripts/regenerate_portals.py

The script prints a candidate VEOLIA_PORTALS block and a diff against the current table — review and edit veolia_api/portals.py manually.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for guidelines on reporting bugs, suggesting features, and submitting pull requests.

Credits

This repository is inspired by the work done by @CorentinGrard. Thanks to him for his work. It is a fork of Jezza34000/veolia-api.

License

This project is licensed under the MIT License. See LICENSE for details.