Home Assistant Water Reservoir Integration: Global Water Reservoirs Guide

This article may contain affiliate links. If you buy through these links, the price is the same for you and the store pays me a small commission that helps keep Tecnoyfoto running.

Albert BarnosellEditor and publisher of Tecnoyfoto

Global Water Reservoirs is a Home Assistant water reservoir integration for public data. It can create sensors for fill percentage, stored volume, capacity, water level and data age whenever the selected source publishes those metrics.

This is an unofficial custom integration developed by Tecnoyfoto. It is not maintained by Home Assistant or by the public agencies supplying the source data. Its current focus is Spain, with early support for selected United States reservoirs through USBR / RISE.

Important: it does not measure household water use, predict droughts or replace official restrictions. It turns public reservoir-storage records into Home Assistant entities for dashboards, history and cautious notifications.

What is Global Water Reservoirs?

Global Water Reservoirs is a community Home Assistant reservoir integration that queries several public hydrological sources and normalizes their results. Data originally published in different formats and units becomes a consistent set of Home Assistant entities.

Its architecture has two levels:

• One hub per data source or basin: this represents the connection to a public provider.
• One device per selected reservoir: this contains only the entities that the source can supply for that reservoir.

Several hubs can coexist in one Home Assistant instance. You might configure one entry for Catalunya and another for the Ebro basin, for example. Integration options allow reservoirs to be added or removed later and the polling interval to be changed.

The public version checked for this guide is 1.1.24. The project is MIT-licensed and actively evolving, so check the changelog before updating.

Home Assistant entities and sensors

The integration does not fabricate missing fields. An entity is created only when the data source returns the required value. Two reservoirs managed by different providers may therefore expose different entity sets.

Capacity, timestamp and data age are diagnostic entities. Device attributes may also include provider, basin, province, source URL and a stale-data flag when the record is more than 72 hours old.

Aggregate hub sensors

Each hub may create a separate summary device for the selected reservoirs:

• Aggregate percentage.
• Total volume.
• Total capacity.
• Returned reservoir count.
• Reservoirs with usable data.
• Reservoirs with records older than 72 hours.
• Latest source timestamp in the group.

How the aggregate percentage is calculated

When volume and capacity are available, the percentage is capacity-weighted:

aggregate percentage = total volume / total capacity × 100

This is more representative than treating a small reservoir and a large reservoir equally. When sufficient volume and capacity data is unavailable, the integration falls back to the average of the published percentages. The sensor attributes identify the method as capacity_weighted or average_percent.

Supported countries, basins and sources

Despite the “Global” name, worldwide coverage is not available yet. The current integration supports Spain and a limited selection of US reservoirs. Stating that boundary clearly is more useful than implying unsupported international coverage.

Spain

Spain is organized into hubs by basin or data source. Depending on the area, the integration uses basin-specific SAIH services, river-basin authority portals, regional open data or MITECO’s reservoir map layer.

• Catalunya.
• Duero, Ebro, Guadiana, Guadalquivir, Júcar, Segura and Tajo basins.
• Miño-Sil and Cantabrian basins.
• Galicia Costa.
• Internal Basque Country basins.
• Mediterranean Andalusian basin.
• Guadalete-Barbate.
• Tinto, Odiel and Piedras.
• A Spain fallback source based on MITECO data.

United States

US support uses the public USBR / RISE system for selected Bureau of Reclamation reservoirs. It is an early and narrower implementation, not a complete US reservoir database.

Why are unsupported countries not added immediately?

An API or downloadable file is not enough. Records must be current, identifiable and reasonably stable. Mexico was investigated, but it was not included because the accessible structured datasets found during development were stale.

Reservoir readings are not always real-time

Global Water Reservoirs uses the Home Assistant cloud polling model and contacts public online services. Polling a service every hour does not make that agency publish a fresh measurement every hour.

Some SAIH systems update several times per day. Other providers publish daily or weekly. The setup flow only offers conservative intervals allowed for each provider—typically between 1 and 24 hours—to avoid pointless or abusive traffic.

Always interpret a reading together with:

1. The sensor value.
2. The official record timestamp.
3. The data-age sensor.

A record older than 72 hours is flagged as stale and included in the stale-reservoir aggregate count. This does not automatically mean the integration has failed; the agency may simply not have published a newer record.

Installing Global Water Reservoirs with HACS

The project currently installs as a custom repository. It is not included in Home Assistant Core, and users should not assume it will appear in the default HACS catalogue before adding the repository.

1. Open HACS → Integrations.
2. Open the three-dot menu and select Custom repositories.
3. Add this URL:

https://github.com/tecnoyfoto/global_water_reservoirs

4. Select Integration as the category.
5. Find Global Water Reservoirs and click Download.
6. Restart Home Assistant when prompted.

The project’s hacs.json declares Home Assistant 2024.6.0 as the minimum supported version. General custom-repository guidance is available in the HACS documentation.

Manual installation

Alternatively, download the repository and copy the integration directory to:

/config/custom_components/global_water_reservoirs/

The folder should contain files such as manifest.json, config_flow.py, sensor.py, coordinator.py, plus the providers and translations directories. Restart Home Assistant afterwards. HACS remains the easier option for updates.

Configuration walkthrough

1. Open Settings → Devices & services.
2. Select Add integration.
3. Search for Global Water Reservoirs.
4. Select the country.
5. Choose a basin or data source.
6. Select one or more reservoirs.
7. Choose one of the update intervals offered for that provider.
8. Finish and wait for the first refresh.

No username, password or API key is required. If the initial reservoir list cannot be fetched, the flow reports a connection error instead of creating an incomplete entry.

Changing reservoirs later

Open Settings → Devices & services → Global Water Reservoirs → Configure. The options flow can add or remove reservoirs and change the interval. Saving reloads that hub automatically.

Dashboard example with historical data

Entity IDs depend on the reservoir name and available sensors. Copy the real ID from Developer tools → States. This example uses Home Assistant’s built-in history card, so no additional HACS card is needed:

type: history-graph
title: Reservoir history
hours_to_show: 336
entities:
  - entity: sensor.local_reservoir_percent
    name: Fill percentage
  - entity: sensor.local_reservoir_volume
    name: Stored volume

The card covers 14 days. A weekly source may only show one or two changes during that period; that is expected and not a recorder fault.

A safer automation: notify without acting blindly

A reservoir percentage is not, by itself, a legal irrigation restriction and does not prove which reservoir supplies a specific property. It is therefore safer to use this information as context and request human review than to directly control a valve.

This example notifies when a reservoir drops below 20%, but only when the source record is less than 72 hours old. Replace the entity IDs and notification service with those from your system:

alias: "Reservoir: low level with recent data"
triggers:
  - trigger: numeric_state
    entity_id: sensor.local_reservoir_percent
    below: 20
conditions:
  - condition: numeric_state
    entity_id: sensor.local_reservoir_data_age
    below: 72
actions:
  - action: notify.mobile_app_my_phone
    data:
      title: "Reservoir storage"
      message: >-
        The reservoir is at {{ states('sensor.local_reservoir_percent') }}%.
        Check official information and local restrictions.
mode: single

Automated irrigation should also consider soil moisture, rain forecast, season, watering windows and municipal rules. Regional storage is useful context, but it should not be the only control input.

Privacy, security and resource use

• No credentials, tokens or external accounts are required.
• The integration only requests public online sources.
• It cannot control dams, valves or infrastructure.
• It uses Home Assistant’s shared HTTP client.
• Provider-specific intervals keep polling conservative.
• Diagnostics contain reservoir identifiers, provider details and normalized public data, but no account passwords.

Like every cloud-polling integration, it depends on public services remaining available and retaining compatible formats. Version 1.1.24, for example, restored secure SAIH Ebro connectivity while keeping TLS verification enabled and added retries for transient failures.

Known limitations

• This is an unofficial community integration.
• Coverage currently means Spain and selected United States reservoirs, not the whole world.
• Not every source publishes percentage, volume, capacity and level together.
• Some records are daily or weekly rather than real-time.
• Institutional portals may change without notice.
• A storage percentage does not replace drought alerts or official restrictions.
• Users must verify which reservoir or system supplies their own municipality.

Troubleshooting

No reservoirs appear during setup

The selected service may be temporarily unavailable or its format may have changed. Try again later, check Home Assistant logs and review open GitHub issues.

A level, capacity or percentage entity is missing

Entities are conditional. When an agency does not publish that metric for a reservoir, the integration avoids creating an empty or estimated sensor.

The value does not change even though Home Assistant refreshes

Check timestamp and data age. Home Assistant may be successfully retrieving the same daily or weekly source record.

I want reservoirs from another basin

Create another Global Water Reservoirs entry for that data source. Each basin runs as an independent hub.

A provider has stopped working

Download the integration diagnostics and open an issue in the Global Water Reservoirs repository, including the affected source and reservoirs.

Frequently asked questions

Is Global Water Reservoirs part of Home Assistant?

No. It is an unofficial custom integration installed through HACS or manually.

Does it measure household water use?

No. Household consumption requires a compatible meter or flow sensor. This integration reads public reservoir-storage information.

Is the data real-time?

That depends on the provider. Some update several times a day; others publish daily or weekly. Timestamp and data-age sensors show the actual freshness.

Can I use it outside Spain?

There is early support for selected US reservoirs through USBR / RISE. Worldwide coverage is not yet available.

Can I request another basin or country?

Yes, through GitHub. A new provider requires a public source that is current, identifiable and reasonably stable.

Conclusion

Global Water Reservoirs turns dispersed public hydrological records into understandable Home Assistant sensors. Its main value is combining percentage, volume, level, timestamp and data age with basin-level summary entities for dashboards and notifications.

Spain has the broadest coverage, while USBR / RISE provides an initial route for selected US reservoirs. The integration does not promise instant readings or universal coverage: it exposes what each agency publishes and helps users judge data quality and freshness.

Install it as a custom repository, begin with one or two reservoirs, and always validate the source timestamp before building automations.

Continue reading

Next related guide · 3 min read

Tapo Cameras in Home Assistant: Official Integration, HACS, and RTSP

Updated August 27, 2026. Tapo cameras can now be added through TP-Link Smart Home, Home Assistant’s official integration. HACS may still provide advanced controls…

Continue with this article↓