Avec la sécheresse très sévère qui s’annonce, suivre le débit des fleuves et des rivières est particulièrement utile : production d’eau potable, irrigation des cultures, refroidissement de centrales électriques, activités touristiques… de nombreux secteurs dépendent directement des eaux de surface. Des données de débit précises et actualisées peuvent les aider à anticiper les déficits hydriques et à s’y adapter.
Dans ce tutoriel, nous allons voir comment accéder au débit d’un cours d’eau en temps réel via l’API Hub’eau et comment exploiter ces données avec Python.
Utiliser l’API du système d’information sur l’eau (SIE)
Avec près de 3000 stations hydrométriques en métropoles et en outremer, le système d’information sur l’eau permet d’obtenir des données de débit en temps réel pour la plupart des cours d’eau français.
Les mesures peuvent être visualisées directement, par exemple via le site Vigiecrues. Cependant ce service ne permet pas de télécharger les données pour faire vos propres analyses, ni d’obtenir des mesures remontant à plus de quelques semaines. Pour cela, il faudra passer par l’API hydrométrie.
Comment fonctionne cette API ? Voici une façon très simple de l’utiliser :
Trouver le code de la station hydrométrique qui vous intéresse : imaginons que l’on veuille obtenir le débit de la Seine à Paris, on peut facilement trouver la station la plus proche grâce à cette carte interactive. C’est la station du pont d’Austerlitz qui porte le code F700000103.
Télécharger les données directement avec l’url correspondant à la station : dans notre cas, il suffit de rentrer dans un navigateur web l’adresse suivante : https://hubeau.eaufrance.fr/api/v1/hydrometrie/observations_tr.csv?code_entite=F700000103. Pour une autre station, il faudra simplement changer le code_entite .
En complétant l’url, vous pouvez affiner un peu plus votre recherche. Voici quelques unes des options :
Par défaut, vous obtenez le débit et la hauteur d’eau, il est possible de ne télécharger que le débit en précisant grandeur_hydro=Q : https://hubeau.eaufrance.fr/api/v1/hydrometrie/observations_tr.csv?code_entite=F700000103&grandeur_hydro=Q
Par défaut, seules les 1000 dernières mesures sont renvoyées, vous pouvez demander une série plus longue avec l’argument size. Par exemple pour obtenir les 2000 dernières mesures : https://hubeau.eaufrance.fr/api/v1/hydrometrie/observations_tr.csv?code_entite=F700000103&grandeur_hydro=Q&size=2000
Vous pouvez définir une date de début, par exemple pour récupérer tous les débits depuis le 1er juin 2022: https://hubeau.eaufrance.fr/api/v1/hydrometrie/observations_tr.csv?code_entite=F700000103&grandeur_hydro=Q&size=10000&date_debut_obs=2022-06-01T00:00:00. Attention l’API limite encore à 1000 mesures par défaut, il faut donc définir également une valeur assez grande pour size.
Exploiter l’API avec Python
Cette méthode simple vous permet d’obtenir les données sous format .csv, vous pouvez donc facilement les ouvrir et les exploiter avec un tableur, par exemple Microsoft Excel ou OpenOffice Calc.
Pour une analyse qui porte sur de nombreuses stations ou qui doit être répétée régulièrement, ce traitement manuel va cependant rapidement devenir pénible… voici donc comment télécharger ces données directement avec Python.
Pour commencer, il va falloir comme précédemment définir l’url à récupérer :
from datetime import datetime, timedelta
#Stations à télécharger
station = "F700000103"
#Période : les 10 derniers jours
url_API = "https://hubeau.eaufrance.fr/api/v1/hydrometrie/observations_tr.csv"
url = url_API+ f"?code_entite={station}&grandeur_hydro=Q&size=10000&date_debut_obs={debut}"
Ensuite, on récupère la réponse de l’API à cette requête et on la met dans un dataframe :
Maintenant, libre à vous d’exploiter ces données comme vous le souhaitez. Pour commencer, on peut par exemple les représenter sur un graphique :
import matplotlib.pyplot as plt
import matplotlib.dates as mdates
#Conversion des dates en datetime
#Conversion des débits en m3/s
df["resultat_obs"] = df["resultat_obs"]/1000
fig, ax = plt.subplots(figsize = (12, 6), facecolor = 'w')
ax.plot(df.date_obs, df.resultat_obs)
#Affichage du cadrillage
ax.grid(True, alpha = 0.5)
#Mise en forme de l'axe des x
days = mdates.DayLocator()
ax.xaxis.set_major_locator(days)
day_fmt = mdates.DateFormatter('%d/%m')
ax.xaxis.set_major_formatter(day_fmt)
#Nom des axes
ax.set_ylabel("Débit (m3/s)")
ax.set_xlabel("Date")
Voici le résultat obtenu :
Application : le débit du jour est-il normal ?
Voici un exemple d’utilisation un peu plus complexe de cette API.
Notre objectif est de savoir si le débit actuel pour une station est normal, ou bien inférieur ou supérieur aux valeurs enregistrées les années précédentes pour la même journée.
Nous allons donc :
Récupérer les débit enregistrés sur les 24 dernières heures et calculer la moyenne,
Récupérer les archives des débits moyens journaliers et calculer la moyenne historique pour le même jour du même mois,
Comparer les deux pour voir si le débit actuel est supérieur ou inférieur à la normale.
Pour récupérer les débits des 24 dernières heures, il suffit de reproduire ce que l’on a déjà fait :
#Stations à télécharger
station = "F700000103"
#Période à récupérer : 1 jour
url_API = "https://hubeau.eaufrance.fr/api/v1/hydrometrie/observations_tr.csv"
url = url_API+ f"?code_entite={station}&grandeur_hydro=Q&size=10000&date_debut_obs={debut}"
with urlopen(Request(url)) as reponse:
#Calcul de la moyenne
debit_24h = df.resultat_obs.mean()
debit_24h = debit_24h / 1000 #Conversion en m3/s
La même API permet de récupérer les historiques de débits moyens journaliers, il suffit de modifier légèrement l’url :
url_API = "https://hubeau.eaufrance.fr/api/v1/hydrometrie/obs_elab.csv"
url = url_API+ f"?code_entite={station}&grandeur_hydro_elab=QmJ&size=10000"
with urlopen(Request(url)) as reponse:
On va sélectionner dans le dataframe obtenu les valeurs correspondants à la date du jour puis faire la moyenne :
#date du jour
from datetime import date
#Conversion des dates en datetime
df["date_obs_elab"] = pd.to_datetime(df["date_obs_elab"], format = '%Y-%m-%d')
#Sélection des mesures effectuées le même jour et le même mois
df_histo_du_jour = df[(df.date_obs_elab.dt.day == date_du_jour.day) &
(df.date_obs_elab.dt.month == date_du_jour.month)]
#Calcul de la moyenne
debit_normal_du_jour = df_histo_du_jour.resultat_obs_elab.mean()
debit_normal_du_jour = debit_normal_du_jour / 1000
Il ne reste plus qu’à calculer la différence entre les deux et à afficher le résultat, par exemple de cette façon :
delta = (debit_24h - debit_normal_du_jour)/ debit_normal_du_jour
print(f"Le débit sur 24h est {'inferieur' if delta < 0 else 'superieur'} \
de {abs(delta)*100:.1f}% au débit normal pour cette journée.")
Et voici le résultat obtenu :
Le débit sur 24h est inférieur de 43.9% au débit normal pour cette journée.A propos : Callendar est une start-up spécialisée dans le développement de solutions innovantes pour l’évaluation des risques climatiques. Conscients du défi que représente l’adaptation au changement climatique, nous nous efforçons de partager notre expertise au travers d’outils gratuits ou de tutoriels comme celui-ci.