aguasgo-py 2026.7.0

Python client for unofficial Global Omnium water API

Aguasgo-py Python API

Programmatic access to water consumption data from Global Omnium, the Spanish water distributor management group.

🚀 Features

• Multi-entity Support: Compatible with various Global Omnium management companies (e.g., Emivasa, Aguas de Valencia, and others).
• Automatic Municipality → Base URL Detection: Enter your municipality during setup; the library resolves the correct API endpoint automatically.
• Modern Python: Fully updated for Python 3.11+ with strong type hinting and asynchronous support (asyncio / aiohttp).
• Consumption Data: Retrieve current readings and hourly/historical consumption.
• Historical Backfill: Fetch complete historical data in chunks (30-day windows) for Home Assistant Energy Dashboard integration.
• Reliable: Robust parsing and session management designed for stable Home Assistant integrations.

📦 Installation

For Development (Editable Mode)

If you are contributing or developing a component based on this library, install it in editable mode:

git clone https://github.com/carlos-48/aguasgo-py.git
cd aguasgo-py
pip install -e .

For Production

pip install aguasgo-py

🛠️ Quick Start

import asyncio
import aiohttp
from aguasgo import Client

async def main():
    async with aiohttp.ClientSession() as session:
        # base_url is mandatory as it depends on the management company of your municipality
        client = Client(
            session=session,
            username="your_username",
            password="your_password",
            base_url="https://www.emivasa.es/VirtualOffice"
        )
        
        # Example: Get current measure
        measure = await client.get_measure()
        print(f"Current Reading: {measure.accumulate} m³")
        print(f"Instant Consumption: {measure.instant} l/h")

asyncio.run(main())

🧪 Testing

The library includes a comprehensive test suite using pytest.

Unit Tests

Run fast, deterministic tests using local fixtures:

pytest tests/unit

Integration Tests

Run tests against the live Global Omnium API (requires credentials):

pytest --run-integration tests/integration

⚖️ License & Attribution

This project is licensed under the GNU General Public License v3.0 (GPLv3).

Attribution Notice: This library is based on the original work by ldotlopez, adapted, refactored, and updated by carlos-48 to migrate from electrical energy data (original project) to water supply data.

🔗 Useful Links

• Home Assistant Component
• Original ideenergy Python API