Skip to main content

Aguasgo-py Python API

GitHub Release CodeQL Code style: black

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.

Metadata

Release files for aguasgo-py 2026.7.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aguasgo-py 2026.7.2
File Size Uploaded Provenance Actions
aguasgo_py-2026.7.2.tar.gz 83.1 kB With provenance Details for aguasgo_py-2026.7.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aguasgo-py 2026.7.2
File Interpreter ABI Platform Actions
aguasgo_py-2026.7.2-py3-none-any.whl Python 3 none any Details for aguasgo_py-2026.7.2-py3-none-any.whl

Total release size: 168.1 kB

Release files / aguasgo_py-2026.7.2.tar.gz

Download URL aguasgo_py-2026.7.2.tar.gz
Size 83.1 kB
Tags Source
SHA-256 checksum
How to use checksums
385f1d000b4565281b6648d0237ffec2007b90201ceca180962a0c6487d4bdcd
BLAKE2b-256 checksum
How to use checksums
c723581bee32e966aa37caefc39942bafbf777412193d774f7ad4fd99395241b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 4, 2026.

Transparency log

Release files / aguasgo_py-2026.7.2-py3-none-any.whl

Download URL aguasgo_py-2026.7.2-py3-none-any.whl
Size 85.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
23602220460bf77b09e2589ff31340c2222c3d5c087c5ffec1a43e6ef672e036
BLAKE2b-256 checksum
How to use checksums
ff89f4776c208c3f6aa7b1109f7a5908129a72654a7cf774de09033aa126abfa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 4, 2026.

Transparency log

Security for aguasgo-py 2026.7.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for aguasgo_py-2026.7.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 4, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page