Nous avons la demande suivante :
Je veux connaître les teneurs en Nitrates de la rivière qui passe près de chez moi et voir si ces teneurs ont tendance à augmenter ou non depuis quelques années. J'habite à Longuyon, en Meurthe et Moselle.
Voyons comment Hub'Eau peut nous aider à répondre à cette question.
Eléments dont j'ai besoin :
Avec ces éléments, je peux construire l'URL à interroger :
Je peux aussi utiliser la "console" de l'API pour construire cette URL. S'il y a plusieurs paramètres, ils sont séparés par le signe '&'. L'ajout de &pretty permet d'avoir une mise en forme des résultats plus lisible.
En entrant cette URL dans un navigateur Web, ou si je suis développeur, en interrogeant cette URL depuis une application informatique, j'obtiens les résultats suivants :
{
"count" : 1,
"first" : "http://hubeau.brgm-rec.fr/api/v1/qualite_rivieres/station_pc?libelle_commune=Longuyon&pretty&page=1&size=1000",
"last" : null,
"prev" : null,
"next" : null,
"api_version" : "1.1.0",
"data" : [ {
"code_station" : "02115725",
"libelle_station" : "LA CRUSNES À LONGUYON",
"uri_station" : "http://id.eaufrance.fr/STQ/02115725",
"durete" : 8,
"coordonnee_x" : 890006.0,
"coordonnee_y" : 6930024.0,
"code_projection" : "26",
"libelle_projection" : "RGF93 / Lambert 93",
"longitude" : 5.619440747,
"latitude" : 49.441280583,
"code_commune" : "54322",
"libelle_commune" : "LONGUYON",
"code_departement" : "54",
"libelle_departement" : "MEURTHE-ET-MOSELLE",
"code_region" : "44",
"libelle_region" : "GRAND-EST",
"code_cours_eau" : "B41-0200",
"nom_cours_eau" : "La Crusnes",
"uri_cours_eau" : "http://id.eaufrance.fr/CEA/B41-0200",
"code_masse_deau" : "B1R547",
"code_eu_masse_deau" : "FRB1R547",
"nom_masse_deau" : "CRUSNES 2",
"uri_masse_deau" : "http://id.eaufrance.fr/MDO/B1R547",
"code_eu_sous_bassin" : null,
"nom_sous_bassin" : null,
"code_bassin" : null,
"code_eu_bassin" : null,
"nom_bassin" : null,
"uri_bassin" : null,
"type_entite_hydro" : "2",
"commentaire" : null,
"date_creation" : "1986-01-01",
"date_arret" : null,
"date_maj_information" : "2017-01-12",
"finalite" : null,
"localisation_precise" : "LA CRUSNES À LONGUYON",
"nature" : null,
"altitude_point_caracteristique" : 219.0,
"point_kilometrique" : null,
"premier_mois_annee_etiage" : null,
"superficie_bassin_versant_reel" : null,
"superficie_bassin_versant_topo" : 258.47,
"geometry" : {
"type" : "Point",
"crs" : {
"type" : "name",
"properties" : {
"name" : "urn:ogc:def:crs:OGC:1.3:CRS84"
}
},
"coordinates" : [ 5.61944074682569, 49.4412805825202 ]
}
} ]
}
On se rend compte qu'on récupère beaucoup de paramètres qui ne nous intéressent pas forcément. Pour réduire la liste des paramètres retournés, on utilise l'attribut fields suivi de la liste des éléments à retourner séparés par une virgule.
Dans notre cas, on voudrait connaître simplement le nom et le code de la station, le cours d'eau sur lequel elle est située, et la commune pour vérifier. Nous n'allons donc utiliser que les éléments code_station, libelle_station, localisation_precise, code_commune, libelle_commune, code_cours_eau, nom_cours_eau.
Notre URL devient donc :
Attention à ne pas inclure d'espaces dans l'URL !
Cette nouvelle requête nous fournit le résultat suivant :
{ "count" : 1, "first" : "http://hubeau.brgm-rec.fr/api/v1/qualite_rivieres/station_pc?libelle_commune=Longuyon&pretty&fields=code_station,libelle_station,localisation_precise,code_commune,libelle_commune,code_cours_eau,nom_cours_eau&page=1&size=1000", "last" : null, "prev" : null, "next" : null, "api_version" : "1.1.0", "data" : [ { "code_station" : "02115725", "libelle_station" : "LA CRUSNES À LONGUYON", "code_commune" : "54322", "libelle_commune" : "LONGUYON", "code_cours_eau" : "B41-0200", "nom_cours_eau" : "La Crusnes", "localisation_precise" : "LA CRUSNES À LONGUYON" } ] }
Ces résultats nous disent qu'il existe une station sur la commune de Longuyon, qui s'appelle LA CRUSNES à LONGUYON, de code 02115725, sur le cours d'eau La Crusnes.
Dans notre cas, nous avons une station de code 02115725.
Eléments dont j'ai besoin :
Avec ces éléments, je peux construire l'URL à interroger :
Voici un extrait des résultats :
{ "count" : 102, "first" : "http://hubeau.brgm-rec.fr/api/v1/qualite_rivieres/analyse_pc?code_station=02115725&libelle_parametre=Nitrates&date_debut_prelevement=2013-01-01&code_qualification=1&pretty&fields=code_station,libelle_station,code_parametre,libelle_parametre,date_prelevement,resultat,symbole_unite,code_remarque,mnemo_remarque,code_statut,mnemo_statut,code_qualification,libelle_qualification&page=1&size=1000", "last" : null, "prev" : null, "next" : null, "api_version" : "1.1.0", "data" : [ { "code_station" : "02115725", "libelle_station" : "LA CRUSNES À LONGUYON", "date_prelevement" : "2013-01-22", "code_parametre" : "1340", "libelle_parametre" : "Nitrates", "resultat" : 25.0, "symbole_unite" : "mg(NO3)/L", "code_remarque" : "1", "mnemo_remarque" : "Résultat > seuil de quantification et < au seuil de saturation ou Résultat = 0", "code_statut" : "2", "mnemo_statut" : "Donnée contrôlée niveau 1 (données contrôlées)", "code_qualification" : "1", "libelle_qualification" : "Correcte" }, { "code_station" : "02115725", "libelle_station" : "LA CRUSNES À LONGUYON", "date_prelevement" : "2013-01-22", "code_parametre" : "1340", "libelle_parametre" : "Nitrates", "resultat" : 25.0, "symbole_unite" : "mg(NO3)/L", "code_remarque" : "1", "mnemo_remarque" : "Résultat > seuil de quantification et < au seuil de saturation ou Résultat = 0", "code_statut" : "2", "mnemo_statut" : "Donnée contrôlée niveau 1 (données contrôlées)", "code_qualification" : "1", "libelle_qualification" : "Correcte" }, { ... ... ... }, { "code_station" : "02115725", "libelle_station" : "LA CRUSNES À LONGUYON", "date_prelevement" : "2016-12-09", "code_parametre" : "1340", "libelle_parametre" : "Nitrates", "resultat" : 20.5, "symbole_unite" : "mg(NO3)/L", "code_remarque" : "1", "mnemo_remarque" : "Résultat > seuil de quantification et < au seuil de saturation ou Résultat = 0", "code_statut" : "2", "mnemo_statut" : "Donnée contrôlée niveau 1 (données contrôlées)", "code_qualification" : "1", "libelle_qualification" : "Correcte" } ] }
Hub'Eau nous renvoie 102 résultats correspondant à notre demande (attribut count en première ligne de la réponse), sur une période s'étalant du 23 janvier 2013 au 9 décembre 2016.
Intéressons-nous un moment à la taille des pages de réponse. Jusqu'à présent, nous n'avons pas précisé cette taille. Hub'Eau a donc utilisé la valeur par défaut de 1000 résultats par page. Maintenant, demandons par exemple des pages de 20 résultats maximum : nous allons ajouter l'élément &size=20 à notre requête :
Voici un extrait de la nouvelle réponse :
{ "count" : 102, "first" : "http://hubeau.brgm-rec.fr/api/v1/qualite_rivieres/analyse_pc?code_station=02115725&libelle_parametre=Nitrates&date_debut_prelevement=2013-01-01&code_qualification=1&pretty&fields=code_station,libelle_station,code_parametre,libelle_parametre,date_prelevement,resultat,symbole_unite,code_remarque,mnemo_remarque,code_statut,mnemo_statut,code_qualification,libelle_qualification&page=1&size=20", "last" : "http://hubeau.brgm-rec.fr/api/v1/qualite_rivieres/analyse_pc?code_station=02115725&libelle_parametre=Nitrates&date_debut_prelevement=2013-01-01&code_qualification=1&pretty&fields=code_station,libelle_station,code_parametre,libelle_parametre,date_prelevement,resultat,symbole_unite,code_remarque,mnemo_remarque,code_statut,mnemo_statut,code_qualification,libelle_qualification&page=6&size=20", "prev" : null, "next" : "http://hubeau.brgm-rec.fr/api/v1/qualite_rivieres/analyse_pc?code_station=02115725&libelle_parametre=Nitrates&date_debut_prelevement=2013-01-01&code_qualification=1&pretty&fields=code_station,libelle_station,code_parametre,libelle_parametre,date_prelevement,resultat,symbole_unite,code_remarque,mnemo_remarque,code_statut,mnemo_statut,code_qualification,libelle_qualification&page=2&size=20", "api_version" : "1.1.0", "data" : [ { "code_station" : "02115725", "libelle_station" : "LA CRUSNES À LONGUYON", "date_prelevement" : "2013-01-22", "code_parametre" : "1340", "libelle_parametre" : "Nitrates", "resultat" : 25.0, "symbole_unite" : "mg(NO3)/L", "code_remarque" : "1", "mnemo_remarque" : "Résultat > seuil de quantification et < au seuil de saturation ou Résultat = 0", "code_statut" : "2", "mnemo_statut" : "Donnée contrôlée niveau 1 (données contrôlées)", "code_qualification" : "1", "libelle_qualification" : "Correcte" }, { ... ... ... }, { "code_station" : "02115725", "libelle_station" : "LA CRUSNES À LONGUYON", "date_prelevement" : "2013-07-09", "code_parametre" : "1340", "libelle_parametre" : "Nitrates", "resultat" : 18.6, "symbole_unite" : "mg(NO3)/L", "code_remarque" : "1", "mnemo_remarque" : "Résultat > seuil de quantification et < au seuil de saturation ou Résultat = 0", "code_statut" : "2", "mnemo_statut" : "Donnée contrôlée niveau 1 (données contrôlées)", "code_qualification" : "1", "libelle_qualification" : "Correcte" } ] }
Nous avons bien sûr toujours 102 résultats correspondant à notre demande, par contre la première page ne liste que les 20 premiers (période du 22 janvier 2013 au 9 juillet 2013). L'attribut next contient l'URL à appeler pour avoir les 20 prochains résultats (notez l'élément &page=2 en fin d'URL). L'attribut last contient l'URL de la dernière page de résultats. On constate qu'il y a 6 pages au total : pour obtenir la totalité des résultats, il faudra appeler successivement 6 URL.
En pratique, vous pouvez utiliser la taille par défaut de 1000 résultats par page. S'il se produit des déconnexions ou des erreurs dans la récupération des résultats, il faudra baisser cette taille.
A noter que la profondeur maximale de recherche est égale à 20 000. Celà signifie que Hub'Eau est limité à 20 000 résultats par jeu de requêtes : (nombre de pages de résultats) * (taille des pages) doit être inférieur à 20 000, quelle que soit la taille des pages. Avec une taille de page par défaut de 1000, vous ne pourrez avoir au maximum que 20 pages de résultats (les résultats suivants ne seront pas retournés par Hub'Eau). Si une requête doit ramener plus de 20 000 résultats, celà signifie qu'elle n'est pas assez discriminante, et qu'elle doit être découpée en plusieurs sous-requêtes.
Vous avez du constater que les résultats sont présentés par dates de prélèvement croissantes par défaut. Pour changer ce comportement, il faut ajouter l'élément &sort=desc à l'URL.
renvoie :
{ "count" : 102, "first" : "http://hubeau.brgm-rec.fr/api/v1/qualite_rivieres/analyse_pc?code_station=02115725&libelle_parametre=Nitrates&date_debut_prelevement=2013-01-01&code_qualification=1&pretty&fields=code_station,libelle_station,code_parametre,libelle_parametre,date_prelevement,resultat,symbole_unite,code_remarque,mnemo_remarque,code_statut,mnemo_statut,code_qualification,libelle_qualification&sort=desc&page=1&size=1000", "last" : null, "prev" : null, "next" : null, "api_version" : "1.1.0", "data" : [ { "code_station" : "02115725", "libelle_station" : "LA CRUSNES À LONGUYON", "date_prelevement" : "2016-12-09", "code_parametre" : "1340", "libelle_parametre" : "Nitrates", "resultat" : 20.5, "symbole_unite" : "mg(NO3)/L", "code_remarque" : "1", "mnemo_remarque" : "Résultat > seuil de quantification et < au seuil de saturation ou Résultat = 0", "code_statut" : "2", "mnemo_statut" : "Donnée contrôlée niveau 1 (données contrôlées)", "code_qualification" : "1", "libelle_qualification" : "Correcte" }, { ... ... ... }, { "code_station" : "02115725", "libelle_station" : "LA CRUSNES À LONGUYON", "date_prelevement" : "2013-01-22", "code_parametre" : "1340", "libelle_parametre" : "Nitrates", "resultat" : 25.0, "symbole_unite" : "mg(NO3)/L", "code_remarque" : "1", "mnemo_remarque" : "Résultat > seuil de quantification et < au seuil de saturation ou Résultat = 0", "code_statut" : "2", "mnemo_statut" : "Donnée contrôlée niveau 1 (données contrôlées)", "code_qualification" : "1", "libelle_qualification" : "Correcte" } ] }
Enfin, il est possible d'interroger plusieurs stations en même temps : il faut construire l'URL avec code_station=code1,code2,code3 (un maximum de 200 codes stations est autorisé). Par exemple :
va lister tous les résultats des analyses de nitrates depuis le 1er août 2016 aux 5 stations dont le code est spécifié :
{ "count" : 13, "first" : "http://hubeau.brgm-rec.fr/api/v1/qualite_rivieres/analyse_pc?code_station=02115725,02115650,02115685,02115700,02115715&libelle_parametre=Nitrates&date_debut_prelevement=2016-08-01&code_qualification=1&pretty&fields=code_station,libelle_station,libelle_parametre,date_prelevement,resultat,symbole_unite,code_remarque&sort=desc&page=1&size=1000", "last" : null, "prev" : null, "next" : null, "api_version" : "1.1.0", "data" : [ { "code_station" : "02115650", "libelle_station" : "LA CHIERS À CONS-LA-GRANDVILLE", "date_prelevement" : "2016-11-14", "libelle_parametre" : "Nitrates", "resultat" : 17.2, "symbole_unite" : "mg(NO3)/L", "code_remarque" : "1" }, { "code_station" : "02115650", "libelle_station" : "LA CHIERS À CONS-LA-GRANDVILLE", "date_prelevement" : "2016-10-18", "libelle_parametre" : "Nitrates", "resultat" : 17.8, "symbole_unite" : "mg(NO3)/L", "code_remarque" : "1" }, { "code_station" : "02115650", "libelle_station" : "LA CHIERS À CONS-LA-GRANDVILLE", "date_prelevement" : "2016-09-19", "libelle_parametre" : "Nitrates", "resultat" : 11.0, "symbole_unite" : "mg(NO3)/L", "code_remarque" : "1" }, { "code_station" : "02115650", "libelle_station" : "LA CHIERS À CONS-LA-GRANDVILLE", "date_prelevement" : "2016-08-24", "libelle_parametre" : "Nitrates", "resultat" : 14.1, "symbole_unite" : "mg(NO3)/L", "code_remarque" : "1" }, { "code_station" : "02115685", "libelle_station" : "LE RUISSEAU DE NANHEUL À PIERREPONT", "date_prelevement" : "2016-12-09", "libelle_parametre" : "Nitrates", "resultat" : 17.9, "symbole_unite" : "mg(NO3)/L", "code_remarque" : "1" }, { "code_station" : "02115685", "libelle_station" : "LE RUISSEAU DE NANHEUL À PIERREPONT", "date_prelevement" : "2016-11-14", "libelle_parametre" : "Nitrates", "resultat" : 17.5, "symbole_unite" : "mg(NO3)/L", "code_remarque" : "1" }, { "code_station" : "02115685", "libelle_station" : "LE RUISSEAU DE NANHEUL À PIERREPONT", "date_prelevement" : "2016-10-18", "libelle_parametre" : "Nitrates", "resultat" : 14.5, "symbole_unite" : "mg(NO3)/L", "code_remarque" : "1" }, { "code_station" : "02115685", "libelle_station" : "LE RUISSEAU DE NANHEUL À PIERREPONT", "date_prelevement" : "2016-09-19", "libelle_parametre" : "Nitrates", "resultat" : 15.9, "symbole_unite" : "mg(NO3)/L", "code_remarque" : "1" }, { "code_station" : "02115685", "libelle_station" : "LE RUISSEAU DE NANHEUL À PIERREPONT", "date_prelevement" : "2016-08-24", "libelle_parametre" : "Nitrates", "resultat" : 15.9, "symbole_unite" : "mg(NO3)/L", "code_remarque" : "1" }, { "code_station" : "02115725", "libelle_station" : "LA CRUSNES À LONGUYON", "date_prelevement" : "2016-12-09", "libelle_parametre" : "Nitrates", "resultat" : 20.5, "symbole_unite" : "mg(NO3)/L", "code_remarque" : "1" }, { "code_station" : "02115725", "libelle_station" : "LA CRUSNES À LONGUYON", "date_prelevement" : "2016-11-14", "libelle_parametre" : "Nitrates", "resultat" : 31.3, "symbole_unite" : "mg(NO3)/L", "code_remarque" : "1" }, { "code_station" : "02115725", "libelle_station" : "LA CRUSNES À LONGUYON", "date_prelevement" : "2016-10-18", "libelle_parametre" : "Nitrates", "resultat" : 15.3, "symbole_unite" : "mg(NO3)/L", "code_remarque" : "1" }, { "code_station" : "02115725", "libelle_station" : "LA CRUSNES À LONGUYON", "date_prelevement" : "2016-08-24", "libelle_parametre" : "Nitrates", "resultat" : 11.5, "symbole_unite" : "mg(NO3)/L", "code_remarque" : "1" } ] }
Les stations interrogées lors de la requête précédente sont les stations les plus proches de La Crusnes à Longuyon, station qui nous sert d'exemple depuis le début. Pour identifier ces stations, nous avons utilisé une requête géographique avec les attributs longitude, latitude et distance qui recherche les objets présents dans un cercle de centre le point de coordonnées longitude, latitude et de rayon distance.
La première requête de ce tutoriel nous a fourni les coordonnées de la station La Crusnes à Longuyon :
"coordinates" : [ 5.61944074682569, 49.4412805825202 ]
En interrogeons Hub'Eau, nous sommes en mesure de récupérer la liste des stations proches avec la requête suivante :
qui nous fournit le code et le libellé des stations dans un rayon de 8 km autour de la station La Crusnes à Longuyon :
{ "count" : 5, "first" : "http://hubeau.brgm-rec.fr/api/v1/qualite_rivieres/station_pc?longitude=5.62&latitude=49.44&distance=8&exact_count=true&format=json&fields=code_station,libelle_station&pretty&page=1&size=20", "last" : null, "prev" : null, "next" : null, "api_version" : "1.1.0", "data" : [ { "code_station" : "02115650", "libelle_station" : "LA CHIERS À CONS-LA-GRANDVILLE" }, { "code_station" : "02115685", "libelle_station" : "LE RUISSEAU DE NANHEUL À PIERREPONT" }, { "code_station" : "02115700", "libelle_station" : "LA CRUSNES À PIERREPONT" }, { "code_station" : "02115715", "libelle_station" : "LE RUISSEAU DES EURANTES À ARRANCY-SUR-CRUSNES" }, { "code_station" : "02115725", "libelle_station" : "LA CRUSNES À LONGUYON" } ] }
Nous avons utilisé pour l'instant les opérations permettant de récupérer des résultats au format JSON, très utilisé par les développeurs. Pour exploiter les résultats dans un tableur, il est sans doute plus judicieux d'utiliser les opérations renvoyant des résultats au format CSV. Il suffit d'ajouter .csv à l'URL de base, par exemple l'URL :
vous permet d'enregistrer un fichier CSV que l'on visualise ici dans un bloc-note :
"code_station";"date_prelevement";"libelle_parametre";"resultat";"symbole_unite";"code_remarque" "02115725";"2013-01-22";"Nitrates";"25.0";"mg(NO3)/L";"1" "02115725";"2013-01-22";"Nitrates";"25.0";"mg(NO3)/L";"1" "02115725";"2013-01-22";"Nitrates";"25.0";"mg(NO3)/L";"1" "02115725";"2013-02-19";"Nitrates";"23.0";"mg(NO3)/L";"1" "02115725";"2013-02-19";"Nitrates";"23.0";"mg(NO3)/L";"1" "02115725";"2013-02-19";"Nitrates";"23.0";"mg(NO3)/L";"1" "02115725";"2013-03-19";"Nitrates";"30.0";"mg(NO3)/L";"1" "02115725";"2013-03-19";"Nitrates";"30.0";"mg(NO3)/L";"1" "02115725";"2013-03-19";"Nitrates";"30.0";"mg(NO3)/L";"1" "02115725";"2013-04-16";"Nitrates";"25.0";"mg(NO3)/L";"1" ... "02115725";"2016-10-18";"Nitrates";"15.3";"mg(NO3)/L";"1" "02115725";"2016-11-14";"Nitrates";"31.3";"mg(NO3)/L";"1" "02115725";"2016-12-09";"Nitrates";"20.5";"mg(NO3)/L";"1"
Nous allons utiliser Excel, qui lit directement les fichiers CSV. La commande Fichier, Ouvrir (en sélectionnant les fichiers de type Texte prn,txt,csv) permet d'ouvrir le fichier et de répartir les différentes informations en colonnes.
Selon la configuration de votre ordinateur, il faudra remplacer les symboles décimaux '.' en ',' pour que les nombres soient correctement reconnus. Vous pouvez alors insérer un graphique de type Nuage de point et visualiser graphiquement les résultats :
Il ne vous reste plus qu'à essayer : rendez-vous sur la page de l'API Qualité des cours d'eau !