API Hydrométrie : version bêta

 

API Hydrométrie

 

Les données publiques de l'API "Hydrométrie" sont issues de la Plate-forme HYDRO Centrale (PHyC), opérée par le Service Central d’Hydrométéorologie et d’Appui à la Prévision des Inondations (SCHAPI). Cette Plate-forme stocke les mesures quasi temps-réel provenant d’environ 3000 stations hydrométriques qui constituent le réseau de mesure français, opéré par les Directions Régionales de l’Environnement de l’Aménagement et du Logement (DREAL) ou autres producteurs (collectivités, etc.). A terme (2020), la plateforme intégrera également les données « temps différé » en remplaçant la banque hydro.

Pour en savoir plus : http://www.eaufrance.fr/observer-et-evaluer/etat-des-milieux/rivieres-et-lacs/hauteurs-et-debits#


L'API permet d'interroger le référentiel hydrométrique ainsi que les observations en quasi temps réel.

Le référentiel hydrométrique est constitué de sites et de stations portant des données d'observations de hauteur d'eau (H) et de débit (Q).

La présente API fournit les observations dites quasi "temps réel", mises à jour par leur producteur toutes les 5 à 60 minutes dans la plateforme source (PHyC du SCHAPI). Hub'Eau interroge la source des données toutes les 2 minutes et maintient une profondeur d'historique égale à 1 mois.

 

Se reporter au dictionnaire SANDRE pour une description détaillée de tous les concepts hydrométriques.

 

L'API est actuellement en phase de bêta-test.

 

NB. Les données renvoyées par Hub'Eau sont paginées. Chaque page renvoie un nombre de résultats égal au paramètre size. La page suivante de résultats est accessible à l'URL indiquée dans l'attribut next de la réponse. Pour plus de précisions, reportez vous au chapitre Pagination de la documentation.
De plus, un tutoriel sur l'API 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 bientôt php sont disponibles dans la partie Exemples de la page de contribution GitHub de Hub'Eau.

 

Console de l'API Spécification Swagger

 

Durant la phase de bêta-test, Faites-nous part de vos commentaires sur le forum de contribution Github
(voir les principes des contributions utilisateurs sur cette page.)

D'avance merci pour votre participation à l'amélioration de l'API !

 

 

Derniers changements

2018

  • 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

Les données sont exposées sous la forme d'une API REST.

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

 

Remarque sur le format des dates : elles sont exprimées en Temps Universel Coordonné (UTC) au format ISO 8601. En France métropolitaine, il faut 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 ; à Mayotte ajouter 3 heures ; à la Réunion ajouter 4 heures.

 

Accessibilité

L'API "Hydrométrie" est accessible :

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

 

Pagination

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.

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 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)

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.

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 : il n'y a en théorie pas de limite sur la profondeur d'accès aux résultats avec ce type de pagination.

 

Limitation commune aux deux types de pagination

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 de l'API (endpoints)

L'API "Hydrométrie temps réel" propose 3 opérations :

  • observations_tr (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).
  • sites (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).
  • stations (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

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)

L'URL à interroger est : http://hubeau.eaufrance.fr/api/vbeta/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

 

Résultat :


{
  "count" : 8166,
  "first" : "http://hubeau.eaufrance.fr/api/vbeta/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/vbeta/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=AoQIP4AAACpZMjUxMDAyMDAxcMLr0ePkAj8FMmIzZDZlODYtZ
             mIzMi00ZTUzLThkZmYtOGZjNzUxNTQwMTll&size=3",
  "api_version" : "beta",
  "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
  } ]
}

 

Console de l'API

 

Dernière mise à jour le 12.11.2018