Hydrométrie

2024

• 10/10/2024 : v2 de l'API, qui appelle les services web SANDRE v2 de la PHyC du SCHAPI.
• 18/03/2024 : rechargement des données d'observations élaborées suite à un recalcul de la PHyC

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

• 03/01/2019 : v1.0.1 : Correction bug sur l'API observations https://github.com/BRGM/hubeau/issues/15

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

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 des mesures 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.

L'API "Hydrométrie" est accessible :

• en http : http://hubeau.brgm-rec.fr/api/v2/hydrometrie/referentiel/stations?code_commune_station=45234&size=20&format=json&pretty
• en https https://hubeau.brgm-rec.fr/api/v2/hydrometrie/referentiel/stations?code_commune_station=45234&size=20&format=json&pretty

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 : http://hubeau.brgm-rec.fr/api/v2/hydrometrie/referentiel/stations?code_commune_station=45234&size=20&format=json&pretty&callback=jquery12

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.

Taille de l'URL

La longueur maximale d'une URL est de 2083 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é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 (QmnJ) 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).

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.brgm-rec.fr/api/v2/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.brgm-rec.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.brgm-rec.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
  } ]
}