• Présentation

    Les mises à jour de la banque ADES sont intégrées quotidiennement à l'API.

    Les données sont exprimées

    • en mètres NGF pour les niveaux (ou cotes) ;
    • en mètres par rapport au repère de mesure pour les profondeurs.

    Testez le démonstrateur de l'API Piézométrie et récupérez le code Javascript qui l'a généré pour construire vous même vos applications basées sur Hub'Eau.

    NOUVEAU : l'opération chroniques_tr permet d'interroger en quasi temps-réel les piézomètres qui télé-transmettent leurs données brutes horaires. Découvrez le tableau des quelques 1500 Piézomètres Temps Réel et un exemple de visualiseur des données Temps Réel.

    Faites-nous part de vos commentaires sur le forum de contribution GitHub.

    Depuis octobre 2022, la disponibilité des endpoints chroniques et chroniques temps réel 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é
    chroniques
    99,88 % 99,90 % 99,85 %
    Disponibilité
    chroniques_tr
    99,78 % 98,85 % 99,84 %

     

  • Derniers changements

    2020
    • 17/03/2020 : v1.4.0 L'opération chroniques est à son tour enrichie avec de nouvelles informations : continuité des mesures, producteur, nature des mesures et profondeur de l'eau par rapport au repère
    • 14/02/2020 : v1.3.0 L'opération stations s'enrichit avec des informations supplémentaires dont l'altitude, la profondeur d'investigation, le département, les masses d'eau captées, le nombre de mesures disponibles... et offre la possibilité de requêter sur de nouveaux paramètre dont la date d'activité et le nombre minimal de mesures disponibles
    • 22/01/2020 : v1.2.0 Mise à disposition de l'opération chroniques_tr permettant d'interroger en quasi-temps réel les piézomètres qui télé-transmettent leurs données
    2019

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

    2018

    25/07/2018 : v1.1.1 et v0.2.1

    • Mise à jour technique permettant d'augmenter la fréquence de mise à jour des données

    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
    2017

    29/11/2017 : mise à jour de la version de l'API : passage de v0 à v1

    • modification de l'URL de l'API : /v0/niveaux_aquiferes par /v1/niveaux_nappes, (pour plus d'informations : http://hubeau.eaufrance.fr/page/api-piezometrie-depreciee)
    • ajout dans la réponse de l'attribut api_version (string) : version de l'API (https://semver.org/)

    04/10/2017 : ajout du paramètre "sort" sur l'opération "chroniques", permet de changer l'ordre de tri (asc ou desc) sur la date de mesure piézométrique
    04/05/2017 : mise à jour de l'adresse de l'API api.hubeau.fr vers hubeau.eaufrance.fr/api/

    2016

    24/11/2016 : ajout de l'attribut "timestamp_mesure" sur l'opération "chroniques" de l'API sur le niveau des aquifères
    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é

    L'API "Piézométrie" est accessible :

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

  • Pagination

    Les méthodes suivent toutes le même modèle de pagination.

    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.

    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

    L'API "Piézométrie" propose différentes opérations :

    • l'opération stations permet d'accéder aux stations de mesure des niveaux des nappes d'eau (piézomètres) ;
    • l'opération chroniques permet d'accéder aux chroniques piézométriques (évolution dans le temps du niveau des nappes) par station de mesure ;
    • l'opération chroniques_tr permet d'accéder en temps quasi-réel aux données piézométriques brutes de fréquence horaire télé-transmises par environ 1400 piézomètres.
  • Exemple

    1. Trouver tous les piézomètres existant à Mâcon :

    Le code INSEE de la commune de Mâcon est 71270. L'URL à interroger est : http://hubeau.eaufrance.fr/api/v1/niveaux_nappes/stations?code_commune=71270&format=json&size=20&pretty
    NB. L'attribut pretty permet d'avoir une réponse plus lisible avec des sauts de ligne et une indentation.

    Résultat :

    {
      "count" : 2,
      "first" : "https://hubeau.eaufrance.fr/api/v1/niveaux_nappes/stations?code_commune=71270&format=json&pretty&page=1&size=20",
      "last" : null,
      "prev" : null,
      "next" : null,
      "api_version" : "1.1.2",
      "data" : [ {
        "code_bss" : "06252X0063/PZ1",
        "urn_bss" : "http://services.ades.eaufrance.fr/pointeau/06252X0063/PZ1",
        "date_debut_mesure" : "2008-05-21",
        "date_fin_mesure" : "2020-02-17",
        "code_commune_insee" : "71270",
        "nom_commune" : "Mâcon",
        "x" : 4.84129654,
        "y" : 46.370535409,
        "codes_bdlisa" : [ "523AB00" ],
        "urns_bdlisa" : [ "http://reseau.eaufrance.fr/geotraitements/bdlisa/files/entite/523AB00.pdf" ],
        "geometry" : {
          "type" : "Point",
          "crs" : {
            "type" : "name",
            "properties" : {
              "name" : "urn:ogc:def:crs:OGC:1.3:CRS84"
            }
          },
          "coordinates" : [ 4.84129654001931, 46.3705354087062 ]
        },
        "bss_id" : "BSS001PYMM",
        "altitude_station" : "214.0",
        "nb_mesures_piezo" : 4258,
        "code_departement" : "71",
        "nom_departement" : "Saône-et-Loire",
        "libelle_pe" : "forage BRGM (Sennece-Les-Macon-71)",
        "profondeur_investigation" : 40.0,
        "codes_masse_eau_edl" : [ "DG503" ],
        "noms_masse_eau_edl" : [ "Domaine formations sédimentaires des Côtes chalonnaise, maconnaise et beaujolaise" ],
        "urns_masse_eau_edl" : [ "http://www.sandre.eaufrance.fr/geo/MasseDEauSouterraine/DG503" ],
        "date_maj" : "Fri Jan 24 16:44:49 CET 2020"
      }, {
        "code_bss" : "06252X0024/EAU",
        "urn_bss" : "http://services.ades.eaufrance.fr/pointeau/06252X0024/EAU",
        "date_debut_mesure" : "1996-10-31",
        "date_fin_mesure" : "2005-11-14",
        "code_commune_insee" : "71270",
        "nom_commune" : "Mâcon",
        "x" : 4.840539342,
        "y" : 46.370471097,
        "codes_bdlisa" : [ "523AB00" ],
        "urns_bdlisa" : [ "http://reseau.eaufrance.fr/geotraitements/bdlisa/files/entite/523AB00.pdf" ],
        "geometry" : {
          "type" : "Point",
          "crs" : {
            "type" : "name",
            "properties" : {
              "name" : "urn:ogc:def:crs:OGC:1.3:CRS84"
            }
          },
          "coordinates" : [ 4.8405393417401, 46.3704710966954 ]
        },
        "bss_id" : "BSS001PYKW",
        "altitude_station" : "214.0",
        "nb_mesures_piezo" : 1463,
        "code_departement" : "71",
        "nom_departement" : "Saône-et-Loire",
        "libelle_pe" : "Forage - 71000 SENNECE LES MACON",
        "profondeur_investigation" : 40.0,
        "codes_masse_eau_edl" : null,
        "noms_masse_eau_edl" : null,
        "urns_masse_eau_edl" : [ ],
        "date_maj" : "Fri Jan 24 16:44:49 CET 2020"
      } ]
    }

    Il y a 2 piézomètres sur la commune de Mâcon, de codes 06252X0063/PZ1 et 06252X0024/EAU. L'un a des données depuis 2008,l'autre entre 1996 et 2005.

    2. Récupérer la chronique piézométrique complète du piézomètre 06252X0063/PZ1 identifié à l'étape précédente :

    L'URL à interroger est : http://hubeau.eaufrance.fr/api/v1/niveaux_nappes/chroniques?code_bss=06252X0063%2FPZ1&size=5000

    Résultat :

    {
      "count" : 4272,
      "first" : "http://hubeau.eaufrance.fr/api/v1/niveaux_nappes/chroniques?code_bss=06252X0063/PZ1&pretty&page=1&size=5000",
      "last" : null,
      "prev" : null,
      "next" : null,
      "api_version" : "1.1.2",
      "data" : [ {
        "code_bss" : "06252X0063/PZ1",
        "urn_bss" : "http://services.ades.eaufrance.fr/pointeau/06252X0063/PZ1",
        "date_mesure" : "2008-05-21",
        "timestamp_mesure" : 1211328000000,
        "niveau_nappe_eau" : 206.89,
        "mode_obtention" : "Valeur mesurée",
        "statut" : "Donnée contrôlée niveau 1",
        "qualification" : "Correcte",
        "code_continuite" : "2",
        "nom_continuite" : "Point lié au point précédent",
        "code_producteur" : "198",
        "nom_producteur" : "Service Géologique Régional Bourgogne (198)",
        "code_nature_mesure" : null,
        "nom_nature_mesure" : null,
        "profondeur_nappe" : 7.11
      }, {
        "code_bss" : "06252X0063/PZ1",
        "urn_bss" : "http://services.ades.eaufrance.fr/pointeau/06252X0063/PZ1",
        "date_mesure" : "2008-05-22",
        "timestamp_mesure" : 1211414400000,
        "niveau_nappe_eau" : 206.84,
        "mode_obtention" : "Valeur mesurée",
        "statut" : "Donnée contrôlée niveau 1",
        "qualification" : "Correcte",
        "code_continuite" : "2",
        "nom_continuite" : "Point lié au point précédent",
        "code_producteur" : "198",
        "nom_producteur" : "Service Géologique Régional Bourgogne (198)",
        "code_nature_mesure" : null,
        "nom_nature_mesure" : null,
        "profondeur_nappe" : 7.16
      }, {
        "code_bss" : "06252X0063/PZ1",
        "urn_bss" : "http://services.ades.eaufrance.fr/pointeau/06252X0063/PZ1",
        "date_mesure" : "2008-05-23",
        "timestamp_mesure" : 1211500800000,
        "niveau_nappe_eau" : 206.8,
        "mode_obtention" : "Valeur mesurée",
        "statut" : "Donnée contrôlée niveau 1",
        "qualification" : "Correcte",
        "code_continuite" : "2",
        "nom_continuite" : "Point lié au point précédent",
        "code_producteur" : "198",
        "nom_producteur" : "Service Géologique Régional Bourgogne (198)",
        "code_nature_mesure" : null,
        "nom_nature_mesure" : null,
        "profondeur_nappe" : 7.2
      },
    ...
    ...
    {
        "code_bss" : "06252X0063/PZ1",
        "urn_bss" : "http://services.ades.eaufrance.fr/pointeau/06252X0063/PZ1",
        "date_mesure" : "2020-03-01",
        "timestamp_mesure" : 1583035200000,
        "niveau_nappe_eau" : 206.78,
        "mode_obtention" : "Valeur mesurée",
        "statut" : "Donnée contrôlée niveau 1",
        "qualification" : "Correcte",
        "code_continuite" : "2",
        "nom_continuite" : "Point lié au point précédent",
        "code_producteur" : "198",
        "nom_producteur" : "Service Géologique Régional Bourgogne (198)",
        "code_nature_mesure" : null,
        "nom_nature_mesure" : null,
        "profondeur_nappe" : 7.22
      }, {
        "code_bss" : "06252X0063/PZ1",
        "urn_bss" : "http://services.ades.eaufrance.fr/pointeau/06252X0063/PZ1",
        "date_mesure" : "2020-03-02",
        "timestamp_mesure" : 1583107200000,
        "niveau_nappe_eau" : 206.74,
        "mode_obtention" : "Valeur mesurée",
        "statut" : "Donnée contrôlée niveau 1",
        "qualification" : "Correcte",
        "code_continuite" : "2",
        "nom_continuite" : "Point lié au point précédent",
        "code_producteur" : "198",
        "nom_producteur" : "Service Géologique Régional Bourgogne (198)",
        "code_nature_mesure" : null,
        "nom_nature_mesure" : null,
        "profondeur_nappe" : 7.26
      } ]
    }

    4272 mesures piézométriques sont disponibles sur le piézomètre 06252X0063/PZ1 à la date de l'interrogation. Les mesures piézométriques récupérées sont les niveaux maximum journaliers, comme dans la banque ADES.

    3. Récupérer les dernières mesures disponibles sur le piézomètre 06252X0063/PZ1 en quasi temps-réel :

    Pour récupérer les données horaires brutes en temps réel, il faut interroger l'opération chroniques_tr. On ajoute le paramètre sort=desc pour avoir les mesures les plus récentes d'abord; size=5 pour n'avoir que les 5 dernières mesures ainsi que pretty pour rendre les résultats plus lisibles. L'URL à interroger est : http://hubeau.eaufrance.fr/api/v1/niveaux_nappes/chroniques_tr?code_bss=06252X0063%2FPZ1&size=5&sort=desc&pretty

    Résultat (interrogation le 05/02/2020 à 14h) :

    {
      "count" : 528,
      "first" : "http://hubeau.eaufrance.fr/api/v1/niveaux_nappes/chroniques_tr?code_bss=06252X0063/PZ1&sort=desc&pretty&page=1&size=5",
      "last" : "http://hubeau.eaufrance.fr/api/v1/niveaux_nappes/chroniques_tr?code_bss=06252X0063/PZ1&sort=desc&pretty&page=106&size=5",
      "prev" : null,
      "next" : "http://hubeau.eaufrance.fr/api/v1/niveaux_nappes/chroniques_tr?code_bss=06252X0063/PZ1&sort=desc&pretty&page=2&size=5",
      "api_version" : "1.1.2",
      "data" : [ {
        "code_bss" : "06252X0063/PZ1",
        "urn_bss" : "http://services.ades.eaufrance.fr/pointeau/06252X0063/PZ1",
        "timestamp_mesure" : 1580889600000,
        "niveau_eau_ngf" : 207.52,
        "longitude" : 4.84129654001931,
        "latitude" : 46.3705354087062,
        "bss_id" : "BSS001PYMM",
        "altitude_station" : null,
        "altitude_repere" : 214.0,
        "date_mesure" : "2020-02-05T08:00:00Z",
        "profondeur_nappe" : 6.48,
        "date_maj" : "2020-02-05"
      }, {
        "code_bss" : "06252X0063/PZ1",
        "urn_bss" : "http://services.ades.eaufrance.fr/pointeau/06252X0063/PZ1",
        "timestamp_mesure" : 1580886000000,
        "niveau_eau_ngf" : 207.52,
        "longitude" : 4.84129654001931,
        "latitude" : 46.3705354087062,
        "bss_id" : "BSS001PYMM",
        "altitude_station" : null,
        "altitude_repere" : 214.0,
        "date_mesure" : "2020-02-05T07:00:00Z",
        "profondeur_nappe" : 6.48,
        "date_maj" : "2020-02-05"
      }, {
        "code_bss" : "06252X0063/PZ1",
        "urn_bss" : "http://services.ades.eaufrance.fr/pointeau/06252X0063/PZ1",
        "timestamp_mesure" : 1580882400000,
        "niveau_eau_ngf" : 207.52,
        "longitude" : 4.84129654001931,
        "latitude" : 46.3705354087062,
        "bss_id" : "BSS001PYMM",
        "altitude_station" : null,
        "altitude_repere" : 214.0,
        "date_mesure" : "2020-02-05T06:00:00Z",
        "profondeur_nappe" : 6.48,
        "date_maj" : "2020-02-05"
      }, {
        "code_bss" : "06252X0063/PZ1",
        "urn_bss" : "http://services.ades.eaufrance.fr/pointeau/06252X0063/PZ1",
        "timestamp_mesure" : 1580878800000,
        "niveau_eau_ngf" : 207.52,
        "longitude" : 4.84129654001931,
        "latitude" : 46.3705354087062,
        "bss_id" : "BSS001PYMM",
        "altitude_station" : null,
        "altitude_repere" : 214.0,
        "date_mesure" : "2020-02-05T05:00:00Z",
        "profondeur_nappe" : 6.48,
        "date_maj" : "2020-02-05"
      }, {
        "code_bss" : "06252X0063/PZ1",
        "urn_bss" : "http://services.ades.eaufrance.fr/pointeau/06252X0063/PZ1",
        "timestamp_mesure" : 1580875200000,
        "niveau_eau_ngf" : 207.52,
        "longitude" : 4.84129654001931,
        "latitude" : 46.3705354087062,
        "bss_id" : "BSS001PYMM",
        "altitude_station" : null,
        "altitude_repere" : 214.0,
        "date_mesure" : "2020-02-05T04:00:00Z",
        "profondeur_nappe" : 6.48,
        "date_maj" : "2020-02-05"
      } ]
    }

    528 mesures piézométriques brutes horaires étaient disponibles sur le piézomètre 06252X0063/PZ1 au 05/02/2020 14h. La mesure la plus récente disponible date du même jour à 8h du matin. Les informations disponibles sont :

    • code_bss et bss_id : code national du piézomètre (respectivement ancien et nouveau code)
    • urn_bss : lien vers la fiche point d'eau ADES du piézomètre
    • longitude et latitude : coordonnées du piézomètre, en degrés décimaux
    • altitude_station et alitude_repere : cote NGF, en mètres, respectivement du sol au droit du piézomètre et du repère de mesures
    • date_mesure : date et heure de la mesure piézométrique
    • timestamp_mesure : un nombre entier correspondant au nombre de millisecondes écoulées entre le 1er janvier 1970 à minuit UTC et le moment de la mesure (peut être négatif si la date est antérieure au 01/01/1970)
    • profondeur_nappe : profondeur du niveau d'eau, en mètres par rapport au repère de mesures
    • niveau_eau_ngf : côte NGF du niveau d'eau, en mètres. niveau_eau_ngf = altitude_repere - profondeur_nappe
    • date_maj : date de mise à jour des données

     

    NB. tous les piézomètres ne disposent pas de données brutes horaires.