• Présentation

    NOUVEAU : une version 2 de l'API est désormais disponible. Cette nouvelle version ajoute de nombreuses informations dans les réponses des différents endpoints, ajoute également des paramètres requêtables (fraction, statut, qualification, réseau, masse d'eau, ...) et corrige des problèmes d'interrogation des conditions environnementales.

    De plus, dans la version v2 de l'API, les données sont dorénavant synchronisées en continu avec la base Naïades.

    Faites-nous part de vos commentaires sur le forum de contribution Github

    Depuis octobre 2022, la disponibilité du endpoint analyse est mesurée par la plateforme Netvigie.
    Les taux de disponibilités sont indiqués ci-dessous sur 1, 3 et 6 mois.
     

    Horizon 1 mois 3 mois 6 mois
    Période 01/02/2024 - 29/02/2024 01/12/2023 - 29/02/2024 01/09/2023 - 29/02/2024
    Disponibilité 91,87 % 96,95 % 98,45 %
  • Derniers changements

    2023

    03/01/2023 : Fermeture de l'API en v1

    2022

    19/07/2022 : v2

    • synchronisation continue des données avec la base Naiades
    • correction des problèmes d'interrogation des conditions environnementales
    • ajout de paramètres requêtables (fraction, statut, qualification, réseau, masse d'eau, ...)
    • ajout de nombreuses informations supplémentaires dans les réponses des différents endpoints
    2019

    08/01/2019 : Fermeture de l'API en v0

    2018

    22/05/2018 : v1.1.0

    • ajout d'une limitation sur la profondeur d'accès aux résultats, le calcul de la profondeur = numéro de la page * nombre maximum de résultats dans une page
    • ajout du header "link" pour le format CSV
    • correction code retour pour le format CSV, gère le code 200 et 206

    26/02/2018 : mise à jour de la version de l'API, passage de v0 à v1.

    • modification de l'URL de l'API : /v0/qualite_rivieres par /v1/qualite_rivieres ;
    • changement de la structure de l'API permettant l'interrogation avec un plus grand nombre de critères et la récupération de plus d'informations comme les conditions environnementales des prélèvements ;
    • mise à disposition des données sur la France entière, y compris DROM (la v0 ne proposant que les bassins Adour-Garonne et Loire-Bretagne).
    2017
    • 29/11/2017 : ajout de dans la réponse de l'attribut api_version (string) : version de l'API (https://semver.org/)
    • 04/05/2017 : mise à jour de l'adresse de l'API api.hubeau.fr vers hubeau.eaufrance.fr/api/
    2016
    • 25/10/2016 : ajout des données qualité des rivières de l'agence de l'eau Loire Bretagne
    • 21/09/2016 : ajout des libellés SANDRE à côté des codes SANDRE dans la réponse
    • 08/08/2016 : ajout du paramètre fields, la valeur est une liste des champs souhaités dans la réponse, par exemple fields=code_station,localisation
  • Exposition des données

    Les formats supportés sont : JSON, GeoJSON et CSV.

  • Accessibilité

    L'API "Qualité des cours d'eau" est accessible :

    Pour gérer le cross-domain, l'API supporte les protocoles :

  • Pagination

    Les opérations sont paginées et suivent le même modèle de pagination non séquentiel, permettant 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.
  • Limitations

    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. Cette limite peut empêcher la récupération de l'intégralité des résultats d'une requête ; il faut alors découper la requête en plusieurs requêtes à l'aide de critères plus discriminants.

    Longueur maximale de l'URL
    La requête est bloquée si la longueur de l'URL dépasse 2 083 caractères.

  • Opérations

    L'API "Qualité des cours d'eau" propose différentes opérations :

    • l'opération "lister les stations de mesure physico-chimiques" (station_pc) permet d'accéder à la liste des stations (lieux de mesure) sur les cours d'eau ou plans d'eau où des prélèvements d'eau ont eu lieu en vue de faire des analyses de la qualité de l'eau ;
    • l'opération "lister les opérations physico-chimiques" (operation_pc) permet d'accéder à la liste des opérations de prélèvement ayant eu lieu sur les stations ;
    • l'opération "lister les conditions environnementales" (condition_environnementale_pc) permet d'accéder à la liste des conditions environnementales (température de l'air, présence de feuilles, mousses, irisations, etc) observées lors des opérations de prélèvements physico-chimiques ;
    • l'opération "lister les analyses physico-chimiques" (analyse_pc) permet d'accéder à la liste des analyses physico-chimiques effectuées sur les échantillons confectionnés lors des opérations de prélèvement sur les différentes stations. Ces analyses concernent des paramètres physico-chimiques tels que : conductivité, nitrates, substances pesticides, métaux lourds...).
  • Exemple

    Demande :
    Récupérer la liste des stations où ont lieu les prélèvements d'eau en rivière en vue d'analyses physico-chimiques sur les communes de Rochefort (code INSEE commune = 17299) et La Rochelle (code 17300)

    URL appelée :
    https://hubeau.eaufrance.fr/api/v2/qualite_rivieres/station_pc?code_commune=17300,17299&size=3&pretty

    Résultats :
    Voir les résultats