• Présentation

    Cette API complète les données piscicoles diffusées par l'API Hydrobiologie des cours d'eau collectées sur des stations référencées par le Sandre, et consolidées à l'échelle du prélèvement élémentaire (source des données : base ASPE opérée par l'OFB).

    La v0 de l'API, basée sur les données de l'ancienne base IMAGE, reste accessible jusqu'au 31 décembre 2022. La documentation de cette ancienne version est accessible à cette adresse.

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

  • Derniers changements

    2022

    16/06/2022 : v1.0.0

    • Version branchée sur les données ASPE, mise à disposition de l'opération observations
    2019

    03/01/2019 : v0.3.1

    • Correction bug sur le paramètre code_espece_poisson de l'API poissons, le filtrage par code_espece_poisson fonctionne de nouveau
    2018

    22/05/2018 : v0.3.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
    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

    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 (fonctionnalité expérimentale), par exemple fields=code_station,localisation

  • Exposition des données

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

  • Accessibilité

  • Pagination

    Chaque page renvoie un nombre de résultats égal au paramètre size.

    L'API Poisson 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

    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.

    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

    Opération observations :

    Elle permet d'accéder aux données des observations piscicoles collectées sur des stations en cours d'eau référencées par le Sandre, et consolidées à l'échelle du prélèvement élémentaire.

  • Exemple

    Demande 1 : Lister les observations où des Ablettes ont été signalées.

    URL appelée : https://hubeau.eaufrance.fr/api/v1/etat_piscicole/observations?code_alternatif_taxon=ABL&size=20
    Résultats : Voir les résultats

     

    Demande 2 : Lister les observations réalisées sur la commune de Longuyon.

    URL appelée : https://hubeau.eaufrance.fr/api/v1/etat_piscicole/observations?libelle_commune=Longuyon&size=100
    Résultats : Voir les résultats

     

    Demande 3 : Lister les observations de gardons en 2021 sur la station de code 05001800.

    URL appelée : https://hubeau.eaufrance.fr/api/v1/etat_piscicole/observations?code_station=05001800&nom_commun_taxon=gardon&date_operation_min=2021-01-01&date_operation_max=2021-12-31&size=50
    Résultats : Voir les résultats

     

    Demande 4 : Lister les observations de chevaines dont la taille est supérieure à 530mm sur la Loire.

    URL appelée : https://hubeau.eaufrance.fr/api/v1/etat_piscicole/observations?libelle_entite_hydro=loire&nom_commun_taxon=chevaine&taille_individu_min=530&size=20
    Résultats : Voir les résultats