# Hub'Eau

Hub'Eau est la plateforme française d'API REST permettant d'accéder aux données ouvertes sur l'eau de façon centralisée et homogène. Développée par l'OFB (Office Français de la Biodiversité) et le BRGM dans le cadre du pôle INSIDE, cette solution permet le téléchargement immédiat de données sur l'eau depuis les principales banques de données nationales. Les données sont automatiquement mises à jour, enrichies de libellés descriptifs et prêtes à l'exploitation.

La plateforme propose plusieurs API couvrant l'hydrométrie (niveaux et débits des cours d'eau), la piézométrie (niveaux des nappes souterraines), la qualité des eaux (nappes et cours d'eau), les prélèvements en eau, l'état piscicole, l'hydrobiologie, la surveillance littorale, l'écoulement des cours d'eau et les produits phytopharmaceutiques. Chaque API supporte les formats JSON, GeoJSON et CSV, avec une pagination intégrée et des mécanismes de filtrage avancés.

## API Hydrométrie - Observations temps réel

L'API Hydrométrie permet d'accéder aux mesures de hauteur et de débit des cours d'eau en temps réel via le SCHAPI (Service Central d'Hydrométéorologie et d'Appui à la Prévision des Inondations). Les données sont disponibles sur un mois glissant avec une mise à jour régulière.

```bash
# Récupérer les informations d'une station hydrométrique
curl "https://hubeau.eaufrance.fr/api/v1/hydrometrie/referentiel/stations?code_station=V720001002&format=json"

# Réponse exemple:
# {
#   "count": 1,
#   "data": [{
#     "code_station": "V720001002",
#     "libelle_station": "Le Rhône à Beaucaire",
#     "libelle_cours_eau": "Le Rhône",
#     "libelle_commune": "Beaucaire"
#   }]
# }

# Récupérer les observations de débit en temps réel (Q = débit)
curl "https://hubeau.eaufrance.fr/api/v1/hydrometrie/observations_tr?code_entite=V720001002&grandeur_hydro=Q&size=1000&sort=desc"

# Récupérer les observations de hauteur (H = hauteur)
curl "https://hubeau.eaufrance.fr/api/v1/hydrometrie/observations_tr?code_entite=V720001002&grandeur_hydro=H&size=1000"
```

## API Hydrométrie - Pagination avec curseur (PHP)

Pour récupérer l'ensemble des données hydrométriques dépassant la limite d'une page, Hub'Eau utilise un système de pagination par curseur. L'attribut `next` de la réponse contient l'URL de la page suivante jusqu'à épuisement des données.

```php
<?php
// Génération du cache des observations hydrométriques avec pagination cursor
$size = 1000;
$url = 'https://hubeau.eaufrance.fr/api/v1/hydrometrie/observations_tr?size='.$size.'&fields=code_site,code_station,grandeur_hydro,date_obs,resultat_obs&sort=desc';

$page = 0;
$raw = file_get_contents($url);
$json = json_decode($raw, true);

// Boucle sur toutes les pages
while ($json['next']) {
    $page++;
    $cache_file = 'cache/_s'.$size.'_page'.$page.'.json';
    $url = $json['next'];

    echo 'page = '.$page.' url = '.$url.'<br>';

    $raw = file_get_contents($url);
    file_put_contents($cache_file, $raw);
    $json = json_decode($raw, true);
}

// Exemple de traitement des débits à plusieurs stations
$tabStations = array(
    'V720001002', // Rhône
    'A302009050', // Rhin
    'M530001010', // Loire
    'O919001001', // Garonne
    'H320000104'  // Seine
);

foreach ($tabStations as $code_sta) {
    // Récupérer les mesures
    $url = "https://hubeau.eaufrance.fr/api/v1/hydrometrie/observations_tr?code_entite=$code_sta&grandeur_hydro=Q&size=$size&sort=asc";
    $raw = file_get_contents($url);
    $json = json_decode($raw, true);

    // Conversion en m3/s (résultat en L/s)
    foreach ($json['data'] as $obs) {
        $debit = $obs['resultat_obs'] / 1000;
        $date = $obs['date_obs'];
    }
}
?>
```

## API Piézométrie - Chroniques piézométriques (R)

L'API Piézométrie fournit les mesures de niveau des nappes d'eau souterraine. Elle permet de récupérer des chroniques historiques ou en temps réel depuis la banque ADES.

```r
# Chargement des paquets R
require(data.table)
require(ggplot2)

# Appel du endpoint chroniques en CSV de l'API Piézo
NPstation <- fread("http://api.hubeau.fr/v1/niveaux_nappes/chroniques.csv?code_bss=08756X0032/F1")

# Conversion des types
NPstation$date_mesure <- as.Date(NPstation$date_mesure)
NPstation$niveau_nappe_eau <- as.numeric(NPstation$niveau_nappe_eau)

# Tracé de la chronique piézométrique
p <- ggplot(NPstation) + geom_path(aes(x=date_mesure, y=niveau_nappe_eau))
p <- p + theme_bw() + labs(x='', y='m NGF', title='08756X0032/F1')
p <- p + scale_x_date(date_breaks = "1 year", date_labels = "%Y")
print(p)
```

## API Qualité des nappes - Analyses chimiques (Python)

L'API Qualité des nappes permet de récupérer les analyses physico-chimiques des eaux souterraines, incluant les produits phytopharmaceutiques et autres paramètres de qualité depuis la banque ADES.

```python
import requests
import pandas as pd
from io import StringIO
import json

def recupere_eau_sout_qualite_par_station(station, start_date, end_date):
    """Récupère les analyses de qualité pour une station donnée."""

    # Compter le nombre d'analyses disponibles
    analyses_number_url = (
        f'http://hubeau.eaufrance.fr/api/v1/qualite_nappes/analyses'
        f'?bss_id={station}&date_debut_prelevement={start_date}'
        f'&date_fin_prelevement={end_date}&size=1'
    )
    analyses_number = json.loads(requests.get(analyses_number_url).text)['count']

    if analyses_number > 0:
        # Récupérer toutes les analyses en CSV
        analyses_content_url = (
            f'http://hubeau.eaufrance.fr/api/v1/qualite_nappes/analyses.csv'
            f'?bss_id={station}&date_debut_prelevement={start_date}'
            f'&date_fin_prelevement={end_date}&size={analyses_number + 1}'
        )
        print(f"Nombre d'analyses pour {station}: {analyses_number}")
        return pd.read_csv(
            StringIO(requests.get(analyses_content_url).text),
            sep=';',
            parse_dates=['date_debut_prelevement']
        )
    return None

# Exemple d'utilisation
df = recupere_eau_sout_qualite_par_station(
    station='BSS000UTKB',
    start_date='2016-01-01',
    end_date='2017-01-01'
)

# Récupérer les stations d'un département
departement = 54
stations_url = f'http://hubeau.eaufrance.fr/api/v1/qualite_nappes/stations?num_departement={departement}&size=20000&fields=bss_id'
response = requests.get(stations_url)
stations = response.json()['data']
print(f"Nombre de stations: {len(stations)}")
```

## API Prélèvements en eau - Chroniques BNPE (Python)

L'API Prélèvements permet d'accéder aux données déclaratives de prélèvements collectées par les agences de l'eau et réunies dans la BNPE (Banque Nationale des Prélèvements en Eau).

```python
import os
import requests
import pandas

# Configuration
base = "http://hubeau.eaufrance.fr/api"
endpoint = "v1/prelevements"
operation = "chroniques"
page_size = 1000
max_results = 20000

years = ["2017", "2018", "2019"]
fields = [
    "code_ouvrage", "nom_ouvrage", "code_commune_insee", "nom_commune",
    "code_departement", "libelle_usage", "volume",
    "code_qualification_volume", "libelle_qualification_volume"
]

# Construction de l'URL
parameters = f"annee={','.join(years)}&fields={','.join(fields)}&size={page_size}"
hubeau_url = f"{base}/{endpoint}/{operation}?{parameters}"

# Récupération de la 1ère page
response = requests.get(hubeau_url).json()
data = response['data']
nb_results = page_size

# Pagination pour récupérer toutes les pages
while response['next'] is not None and nb_results < max_results:
    hubeau_url = response['next']

    # Ajuster la taille de la dernière page si nécessaire
    if (nb_results + page_size) >= max_results:
        hubeau_url = hubeau_url.replace(
            f"size={page_size}",
            f"size={max_results - nb_results}"
        )

    response = requests.get(hubeau_url).json()
    data += response['data']
    nb_results += page_size

print(f"Nb de résultats récupérés : {len(data)}")

# Conversion en DataFrame et export CSV
df = pandas.DataFrame(data)
df.to_csv("bnpe_chroniques.csv", sep=';', index=False, encoding='utf8')
```

## API Écoulement des cours d'eau - Observations ONDE (Python)

L'API Écoulement donne accès aux observations d'écoulement réalisées par l'OFB dans le cadre de l'observatoire ONDE pour le suivi des étiages.

```python
import requests
import pandas
import geopandas
import time

class Hubeau:
    """Classe d'interfaçage avec Hub'Eau."""

    def __init__(self, response_format="json", page_size=1000):
        self._base = "http://hubeau.eaufrance.fr/api"
        self._response_format = response_format
        self._page_size = page_size
        self.max_results = 20000

    def search(self, endpoint, operation, parameters):
        """Effectue une recherche Hub'Eau avec pagination automatique."""
        params = "&".join([f"{k}={v}" for k, v in parameters.items()])
        url = f"{self._base}/{endpoint}/{operation}?{params}&format={self._response_format}&size={self._page_size}"

        results = []
        next_url = f"{url}&page=1"

        while next_url:
            response = requests.get(next_url)
            if not response.ok:
                break

            response_json = response.json()
            key = 'features' if self._response_format == 'geojson' else 'data'
            results += response_json[key]

            if len(results) >= self.max_results or not response_json['next']:
                break
            next_url = response_json['next']

        if self._response_format == "geojson":
            return geopandas.GeoDataFrame.from_features({
                "type": "FeatureCollection",
                "features": results
            })
        return pandas.DataFrame(results)

# Utilisation pour récupérer les observations d'écoulement 2022
hubeau = Hubeau(response_format="json")

parameters = {
    "date_observation_min": "2022-01-01",
    "date_observation_max": "2022-12-31",
    "fields": "code_station,libelle_station,code_departement,date_observation,code_ecoulement,libelle_ecoulement,latitude,longitude"
}

df = hubeau.search("v1/ecoulement", "observations", parameters)
print(f"Observations récupérées: {len(df)}")

# Export en GeoPackage (format geojson)
hubeau_geo = Hubeau(response_format="geojson")
gdf = hubeau_geo.search("v1/ecoulement", "observations", parameters)
gdf.to_file("onde_observations_2022.gpkg", driver='GPKG')
```

## API Qualité des cours d'eau - Stations et analyses (Python)

L'API Qualité des cours d'eau permet d'accéder aux données de qualité physico-chimique depuis la banque Naïades, incluant les stations de mesure et les analyses.

```python
import requests
import pandas
import geopandas
import folium

# Configuration
base = "http://hubeau.eaufrance.fr/api"
endpoint = "v2/qualite_rivieres"

# Récupérer les stations d'une commune
city_code = "57032"  # Ars-sur-Moselle
station_fields = "code_station,libelle_station,longitude,latitude,code_commune,libelle_commune,code_cours_eau"

station_url = f"{base}/{endpoint}/station_pc?code_commune={city_code}&fields={station_fields}"
response = requests.get(station_url).json()

# Créer un GeoDataFrame
df_station = pandas.DataFrame(response["data"])
geodf_station = geopandas.GeoDataFrame(
    df_station,
    geometry=geopandas.points_from_xy(df_station["longitude"], df_station["latitude"])
)

# Cartographier avec Folium
folium_map = folium.Map(location=[49.07, 6.08], zoom_start=12)
folium.GeoJson(geodf_station.to_json(), name="Stations").add_to(folium_map)
folium_map.save("carte_stations.html")

# Récupérer les analyses pour un paramètre spécifique
station_code = "02079050"
parameter_code = "1375"  # Sodium (code Sandre)

analyse_url = (
    f"{base}/{endpoint}/analyse_pc"
    f"?code_station={station_code}&code_parametre={parameter_code}"
    f"&code_qualification=1&fields=date_prelevement,libelle_parametre,resultat,symbole_unite"
)

response = requests.get(analyse_url).json()
df_analyses = pandas.DataFrame(response["data"])
print(df_analyses.head())
# Sortie:
#   date_prelevement libelle_parametre  resultat symbole_unite
# 0       1995-12-31            Sodium      99.0      mg(Na)/L
# 1       1996-01-01            Sodium     101.0      mg(Na)/L
```

## Formats de réponse et paramètres communs

Toutes les API Hub'Eau supportent plusieurs formats de sortie et des paramètres de pagination standardisés permettant une utilisation cohérente.

```bash
# Format JSON (défaut)
curl "https://hubeau.eaufrance.fr/api/v1/hydrometrie/observations_tr?code_entite=V720001002&format=json"

# Format CSV pour import direct dans un tableur ou pandas
curl "https://hubeau.eaufrance.fr/api/v1/niveaux_nappes/chroniques.csv?code_bss=08756X0032/F1"

# Format GeoJSON pour les données géographiques
curl "https://hubeau.eaufrance.fr/api/v1/ecoulement/observations?format=geojson&code_departement=22"

# Paramètres de pagination
# size: nombre de résultats par page (max 5000 selon API)
# page: numéro de page
curl "https://hubeau.eaufrance.fr/api/v1/qualite_nappes/stations?num_departement=54&size=1000&page=1"

# Sélection des champs retournés
curl "https://hubeau.eaufrance.fr/api/v1/prelevements/chroniques?fields=code_ouvrage,volume,libelle_usage&size=100"

# Structure de réponse JSON
# {
#   "count": 12345,          # Nombre total de résultats
#   "first": "url...",       # URL de la première page
#   "prev": "url...",        # URL de la page précédente
#   "next": "url...",        # URL de la page suivante (null si dernière)
#   "last": "url...",        # URL de la dernière page
#   "data": [...]            # Données de la page courante
# }
```

## Résumé des cas d'usage et intégrations

Hub'Eau s'adresse aux développeurs, data scientists, gestionnaires de l'eau et chercheurs souhaitant exploiter les données hydrologiques françaises. Les cas d'usage principaux incluent : le suivi en temps réel des niveaux d'eau pour la prévention des inondations, l'analyse de la qualité des ressources en eau pour la surveillance environnementale, l'étude des prélèvements pour la gestion quantitative, et la cartographie interactive des stations de mesure.

Les intégrations typiques comprennent des tableaux de bord de suivi hydrologique avec des bibliothèques comme Highcharts ou Plotly, des applications cartographiques utilisant Leaflet ou Folium, des pipelines de données avec pandas/geopandas pour l'analyse statistique, et des scripts d'archivage automatisé pour constituer des historiques de données. La plateforme est compatible avec tous les langages (Python, R, PHP, JavaScript) grâce à son architecture REST standard. Des packages dédiés existent également sur CRAN (package R hubeau) et PyPI (cl-hubeau) pour simplifier l'accès aux données.