Suivre les débits des cours d'eau avec l'API Hub'Eau

Le service public Hub'Eau diffuse en open data les mesures des stations hydrométriques françaises. Ce cas d'usage les importe pour un territoire, l'Ille-et-Vilaine, et les tient à jour automatiquement, puis les rend lisibles d'un clic : une carte des stations qui, quand on en sélectionne une, affiche l'évolution de son débit.

L'API Hydrométrie est publique : aucune clé n'est nécessaire. Ce cas d'usage en utilise deux points d'accès :

• https://hubeau.eaufrance.fr/api/v2/hydrometrie/referentiel/stations — le référentiel des stations : leur code, leur nom, le cours d'eau mesuré, la commune et les coordonnées ;
• https://hubeau.eaufrance.fr/api/v2/hydrometrie/obs_elab — les observations élaborées, calculées à partir des mesures brutes. Le paramètre grandeur_hydro_elab=QmnJ demande le débit moyen journalier, en litres par seconde.

Chaque appel renvoie une page de résultats dans un objet englobant, qui porte aussi le lien vers la page suivante [1]. Les mesures sont dans le tableau data [2] : une par station et par jour, avec le code de la station, la date, la valeur du débit et son statut [3]. Chaque mesure répète enfin les coordonnées de sa station [4].

Le statut évolue : une mesure récente arrive en Donnée brute, puis passe en Donnée validée après expertise. Réimporter régulièrement les données, comme le fera le traitement, intègre ces corrections.

Deux comportements de l'API, vérifiés sur des appels réels, dictent la forme de l'adresse :

• obs_elab ignore le filtre code_departement : il renvoie alors les mesures de toute la France, soit des dizaines de millions de lignes. Il faut délimiter le territoire par un rectangle de coordonnées, le paramètre bbox (longitude et latitude minimales, puis maximales). Le rectangle de l'Ille-et-Vilaine déborde un peu sur les départements voisins : leurs stations seront importées, mais n'apparaîtront pas sur la carte, qui ne montre que les stations du département.
• Le paramètre fields, qui limite les champs renvoyés, vide les coordonnées (longitude et latitude à null). Inutile de s'en servir : c'est le traitement qui choisit les colonnes à garder.

Enfin, date_debut_obs_elab limite l'historique importé : depuis le 1er janvier 2024, l'Ille-et-Vilaine compte environ 100 000 mesures.

Créez un premier traitement Import depuis une API JSON. Dans l'onglet Source des données, l'URL de l'API est :

https://hubeau.eaufrance.fr/api/v2/hydrometrie/referentiel/stations?code_departement=35&en_service=true

Sur ce point d'accès, code_departement fonctionne, et en_service=true écarte les stations fermées. La pagination se règle comme pour les débits, décrits en détail ci-dessous : Lien vers la page suivante dans la réponse, chemin next.

Dans l'onglet Champs à récupérer, le chemin du tableau de résultats est data, et les colonnes sont :

Une exécution produit un jeu de données de 46 stations en service.

Créez un second traitement Import depuis une API JSON, dont l'URL de l'API [1] porte les trois paramètres vus plus haut :

https://hubeau.eaufrance.fr/api/v2/hydrometrie/obs_elab?bbox=-2.29,47.63,-1.01,48.71&grandeur_hydro_elab=QmnJ&date_debut_obs_elab=2024-01-01

La réponse contenant le lien vers la suite, choisissez la pagination Lien vers la page suivante dans la réponse [2], avec next comme Chemin de l'URL de la page suivante [3]. Pour limiter le nombre d'appels, demandez aussi de grandes pages [4] : Paramètre « limit » size, et 5000 éléments par page, ce qui fait une vingtaine d'appels pour l'historique complet.

Le Chemin du tableau de résultats est data [1]. Quatre Colonnes [2] suffisent : les coordonnées sont déjà dans le jeu des stations, inutile de les répéter sur chaque mesure.

À la première exécution, le traitement lit toutes les pages, puis crée un jeu de données fichier, que chaque exécution suivante remplace entièrement. Planifiez-le par exemple une fois par semaine : les nouvelles mesures s'ajoutent, et celles qui ont été validées entre-temps sont corrigées.

La date de début étant fixe, le volume grandit avec le temps : avancez date_debut_obs_elab de temps en temps si l'historique ancien ne vous sert plus.

Pour que la carte des stations sache retrouver les débits d'une station, les deux jeux de données doivent désigner la colonne code_station par un même concept. Aucun concept standard ne correspond à ce code : un administrateur de l'organisation crée donc un concept privé, ici Code station hydrométrique, comme l'explique le cours sur les concepts privés.

Dans chacun des deux jeux, ouvrez Structure → Schéma, sélectionnez la colonne code_station [1], choisissez ce concept dans le champ Concept [2], puis cliquez sur Enregistrer, en haut de la section Structure.

Dans le jeu des stations, associez aussi longitude et latitude aux concepts Longitude et Latitude, pour que la plateforme place les stations sur une carte, et libelle_station au concept Libellé.

Créez une visualisation Graphiques sur le jeu des débits, avec les réglages suivants :

Sur deux ans et demi, un point par mois garde la courbe lisible, là où un point par jour la brouille. Tel quel, le graphique fait la moyenne de toutes les stations. C'est la carte qui le filtrera sur la station sélectionnée.

Créez une visualisation Atelier cartographique et ajoutez un calque sur le jeu des stations. Dans la section Détails au clic du calque :

• Champs affichés : libelle_station et cours_eau ;
• choisissez Afficher une visualisation, avec code_station comme Colonne du filtre, puis l'application du graphique créée à l'étape précédente.

La colonne du filtre porte le concept Code station hydrométrique : au clic sur une station, la carte transmet son code au graphique, qui ne montre plus que les débits de cette station.

Un clic sur une station ouvre le panneau Sélection [1] : le nom de la station et du cours d'eau, puis l'évolution de son débit moyen mensuel. Ici le Nançon, à Lécousse près de Fougères, avec ses crues des hivers 2025 et 2026.

Si vous avez des remarques sur ce cours, n'hésitez pas à nous les communiquer.