• Présentation

    L'API permet d'interroger le référentiel hydrométrique (sites et stations d'observations du réseau français de mesures) ainsi que les observations de hauteur d'eau (H) et de débit (Q) dites "temps réel", bancarisées toutes les 5 à 60 minutes dans la plateforme PHyC.

    L'API est mise à jour à partir de la plateforme PHyC toutes les 2 minutes et maintient un historique d'un mois.

    Depuis le 24 novembre 2021, deux types d'observations "élaborées" (débits moyens journaliers et débits moyens mensuels) sont dorénavant disponibles sur tout l'historique (depuis 1900 pour certaines stations) pour plus de 4200 stations. Les données sont mises à jour quotidiennement.

    Perturbation temporaire : un traitement de recalcul de masse est en cours sur la plate-forme HYDRO Centrale (PHyC), utilisée comme source pour les observations élaborées exposées par l'API Hydrométrie. Cette opération perturbe le process d'alimentation des données de débit moyen journalier.
    Le recalcul doit se poursuivre jusqu’au 18/03/2024, les données seront de nouveau exposées par l’API après cette date.

    Depuis octobre 2022, la disponibilité des endpoints observations_tr et stations 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é
    observations_tr
    99,86 % 99,86 % 99,85 %
    Disponibilité
    stations
    92,80 % 96,39 % 96,45 %

     

  • Derniers changements

    2021
    • 24/11/2021 : Mise à disposition des opérations Observations élaborées (débits moyens journaliers et mensuels) aux formats JSON et CSV.
    2020
    • 05/03/2020 : Passage sur serveur dédié pour tenir la charge (10 appels/s en moyenne).
    2019
    2018
    • 03/12/2018 : suppression de la version beta, passage en production de la v1
    • 29/11/2018 : endpoints observations : ajout du paramètre timestep permettant la récupération de données à un pas de temps déterminé
    • 12/11/2018 : endpoints xml : les valeurs du paramètre fields sont maintenant les noms des champs xml
    • 25/10/2018 : endpoints observations : changement de l'ordre de tri par défaut, le tri par défaut est maintenant date d'observation décroissante (desc) permettant d'obtenir d'abord les observations les plus récentes
    • 08/10/2018 : endpoints observations : correction bug curseur (paramètre cursor), le tri ne concerne maintenant plus que la date d'observation (date_obs), tri ascendant par défaut (les données les plus anciennes d'abord)
    • 20/09/2018 : version bêta publique
    • 10/07/2018 : prototype à des fins de tests internes au SCHAPI
  • Exposition des données

    Unités des observations

    Les observations sont exprimées dans les unités suivantes :

    • mm pour les hauteurs d'eau (diviser par 1000 pour convertir en mètres) ;
    • l/s pour les débits (diviser par 1000 pour convertir en m3/s).
    Dates

    Les dates sont exprimées en Temps Universel Coordonné (UTC) au format ISO 8601.

    • En France métropolitaine, ajouter 1 heure à l'heure UTC en période d'heure d'hiver, et 2 heures en période d'heure d'été.
    • En Guadeloupe et Martinique, soustraire 4 heures à l'heure UTC ;
    • En Guyane soustraire 3 heures à l'heure UTC ;
    • A Mayotte ajouter 3 heures à l'heure UTC ;
    • A la Réunion ajouter 4 heures à l'heure UTC.
    Formats

    Les formats supportés sont : JSON, GeoJSON, CSV et XML SANDRE Hydrométrie.

  • Accessibilité

  • Pagination

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

    Deux modèles de pagination différents sont utilisés selon les opérations.

    Opérations liées au référentiel (sites et stations)

    Le type de pagination pour les sites et stations n'est pas séquentiel et 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.
    Opération observations_tr (observations temps réel)

    Le type de pagination est séquentiel (basé sur l'utilisation de curseurs) : il nécessite l'interrogation séquentielle des résultats. Le bénéfice est que la profondeur d'accès aux résultats est en théorie illimitée

    Paramètres

    • cursor : le curseur de pagination
    • 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
    • L'attribut first permet d'accéder à la première page des résultats,
    • Contrairement au modèle de pagination précédent, l'attribut last n'est pas disponible (interrogation séquentielle 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.
    Pour en savoir plus :
    • Consulter le tutoriel sur l'API Qualité des cours d'eau qui explique, dans la section Taille des pages de réponse, la mise en oeuvre pratique de la pagination à l'aide d'un cas concret.
    • Consulter les exemples de code en Python, R et php proposés dans la section Exemples de la page de contribution GitHub de Hub'Eau.
  • Limitations

    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.

    Taille de page

    Opérations liées au référentiel (sites et stations)

    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."

    Opération observations_tr (observations temps réel)

    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

    Opérations liées au référentiel (sites et stations)

    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 reste bien au-delà du nombre maximal de sites ou de stations, donc n'empêche pas la récupération de l'intégralité des sites ou des stations.

    Opération observations_tr (observations temps réel)

    Il n'y a en théorie pas de limite sur la profondeur d'accès aux résultats avec ce type de pagination.

  • Opérations

    Opération obs_elab :

    Cette opération (Lister les observations élaborées) permet de lister 2 types d'observations dites "élaborées" : les débits moyens journaliers (QmJ) ainsi que les débits moyens mensuels (QmM) sur l'ensemble de l'historique disponible.

    Opération observations_tr :

    Cette opération (Lister les observations hydrométriques) permet de lister les observations dites "temps réel" portées par le référentiel (sites et stations hydrométriques), à savoir les séries de données de hauteur d'eau (H) et de débit (Q).

    Opération sites :

    Cette opération (Lister les sites hydrométriques) permet d'interroger les sites du référentiel hydrométrique (tronçon de cours d'eau sur lequel les mesures de débit sont réputées homogènes et comparables entre elles). Un site peut posséder une ou plusieurs stations ; il est support de données de débit (Q).

    Opération stations :

    Cette opération (Lister les stations hydrométriques) permet d'interroger les stations du référentiel hydrométrique. Une station peut porter des observations de hauteur et/ou de débit (directement mesurés ou calculés à partir d'une courbe de tarage).

  • Exemple

    Demande :

    Interrogation des 3 derniers résultats de niveau d'eau sur la station "L'Orb à Bédarieux", qui renvoie des mesures toutes les 5 minutes (code station = Y251002001) avec sélection d'un choix limité d'attributs à retourner (code station, début et fin de la série de mesures, date et résultat de l'observation)

    URL appelée :

    L'URL à interroger est : http://hubeau.eaufrance.fr/api/v1/hydrometrie/observations_tr?code_entite=Y251002001&size=3&pretty&grandeur_hydro=H&fields=code_station,date_debut_serie,date_fin_serie,date_obs,resultat_obs,continuite_obs_hydro
    NB. L'attribut pretty permet d'avoir une réponse plus lisible avec des sauts de ligne et une indentation.

    Résultat :
    {
      "count" : 8166,
      "first" : "http://hubeau.eaufrance.fr/api/v1/hydrometrie/observations_tr?code_entite=Y251002001&pretty&grandeur_hydro=H&fields=code_station,date_debut_serie,date_fin_serie,date_obs,resultat_obs,continuite_obs_hydro&cursor=&size=3",
      "prev" : null,
      "next" : "http://hubeau.eaufrance.fr/api/v1/hydrometrie/observations_tr?code_entite=Y251002001&pretty&grandeur_hydro=H&fields=code_station,date_debut_serie,date_fin_serie,date_obs,resultat_obs,           continuite_obs_hydro&cursor=AoQIP4AAACpZMjUxMDAyMDAxcMLr0ePkAj8FMmIzZDZlODYtZmIzMi00ZTUzLThkZmYtOGZjNzUxNTQwMTll&size=3",
      "api_version" : "1.0.0",
      "data" : [ {
        "code_station" : "Y251002001",
        "date_debut_serie" : "2018-07-23T00:05:01Z",
        "date_fin_serie" : "2018-07-23T13:25:00Z",
        "date_obs" : "2018-07-23T13:25:00Z",
        "resultat_obs" : 93.0,
        "continuite_obs_hydro" : true
      }, {
        "code_station" : "Y251002001",
        "date_debut_serie" : "2018-07-23T00:05:01Z",
        "date_fin_serie" : "2018-07-23T13:25:00Z",
        "date_obs" : "2018-07-23T13:20:00Z",
        "resultat_obs" : 97.0,
        "continuite_obs_hydro" : true
      }, {
        "code_station" : "Y251002001",
        "date_debut_serie" : "2018-07-23T00:05:01Z",
        "date_fin_serie" : "2018-07-23T13:25:00Z",
        "date_obs" : "2018-07-23T13:15:00Z",
        "resultat_obs" : 99.0,
        "continuite_obs_hydro" : true
      } ]
    }