De par la localisation des stations Onde en tête de bassin versant souvent peu instrumentées, cette API complète les données diffusées par l'API Hydrométrie collectées par le Schapi. La répartition des stations Onde (réseau de plus de 3200 stations) a été pensée pour être représentative du contexte hydrographique des petits et moyens cours d’eau de chaque département. Le mode de recueil des données Onde est exclusivement l’observation visuelle selon des modalités de perturbations d'écoulement des cours d’eau, aucune mesure n’est mise en œuvre sur le terrain.
Ecoulement des cours d'eau
L'API Ecoulement des cours d'eau diffuse les données de l’observatoire national des étiages, Onde, https://onde.eaufrance.fr/. Ces données résultent d'observations visuelles de l’écoulement des petits et moyens cours d’eau réalisées par les agents départementaux de l'Office français de la biodiversité (OFB) pendant la période estivale. Elles couvrent la France hexagonale (Corse comprise) et plus de 10 ans de collecte.
-
Présentation
-
Derniers changements
- 26/05/2023 : arrêt de la version bêta
- 23/05/2023 : passage en version 1
- 29/06/2022 : mise à disposition de la version bêta
-
Exposition des données
Les formats supportés sont : JSON, GEOJSON et CSV.
-
Accessibilité
L'API écoulement des cours d'eau est la première API de Hub'Eau à être conforme au standard OpenAPI 3. Les autres APIs passeront progressivement à ce nouveau standard.
L'API est accessible :
- en http : http://hubeau.eaufrance.fr/api/v1/ecoulement/observations?format=json&code_station=A0220651&size=20
- en https : https://hubeau.eaufrance.fr/api/v1/ecoulement/observations?format=json&code_station=A0220651&size=20
Pour gérer le cross-domain, l'API supporte les protocoles :
- CORS (Cross Origin Resource Sharing)
- JSONP avec le paramètre callback pour les anciens navigateurs : https://hubeau.eaufrance.fr/api/v1/ecoulement/observations?format=json&code_station=A0220651&size=20&callback=jquery12
-
Pagination
Chaque page renvoie un nombre de résultats égal au paramètre size.
L'API Qualité de l'eau potable utilise un type de pagination non séquentiel qui permet de sauter d'une page à l'autre de résultats dans n'importe quel ordre. En contre-partie, la profondeur d'accès aux résultats est limitée.
Paramètres
- page : le numéro de page
- size : la taille de la page
Attributs
- Les attributs prev et next (définis à null si il n'y a pas de page précédente et/ou suivante) sont disponibles dans l'URL de la réponse pour éviter d'avoir à calculer les pages précédentes et/ou suivantes
- L'attribut first permet d'accéder à la première page des résultats,
- L'attribut last permet d'accéder à la dernière page des résultats,
- L'attribut count permet de compter le nombre total de résultats,
- L'attribut data permet d'accéder aux résultats sous forme de liste.
Un tutoriel sur l'API Qualité des cours d'eau explique, dans la partie Taille des pages de réponse, la mise en oeuvre pratique de la pagination à l'aide d'un cas concret.
Enfin, des exemples de code en Python, R et php sont disponibles dans la partie Exemples de la page de contribution GitHub de Hub'Eau. -
Limitations
Pagination
- Taille de page : les résultats sont paginés avec une valeur par défaut et une valeur maximum de taille de page pour chaque opération. Cette valeur est indiquée dans les commentaires de l'opération. Par exemple : "taille de page par défaut : 5000, taille max de la page : 20000."
- Profondeur d'accès aux résultats : la profondeur d'accès aux résultats (numéro de la page * nombre maximum de résultats dans une page) est limitée à 20 000 enregistrements.
Taille de l'URL
La longueur maximale d'une URL est de 2 083 caractères, la requête est bloquée si la limite de longueur est dépassée.
-
Opérations
- stations : permet de connaître les stations sur lesquelles sont réalisées les campagnes d'observation des écoulements ;
- campagnes : permet de lister les campagnes d'observations ;
- observations : permet de consulter les résultats des observations visuelles.
-
Exemple
Liste des stations du département des Vosges :
https://hubeau.eaufrance.fr/api/v1/ecoulement/stations?format=json&code_departement=88&size=20
Liste des stations du département des Vosges, avec affichage jusqu'à 50 éléments par page et récupération des champs code_station, libelle_station et libelle_cours_eau seulement :
Campagnes ayant eu lieu dans le département des Vosges depuis 2021 :
https://hubeau.eaufrance.fr/api/v1/ecoulement/campagnes?date_campagne_min=2021-01-01&code_departement=88&size=20
Observations sur la Moselle, dans le département des Vosges, depuis 2021 :
swagger