API Indicateurs des services

 

 

Les données de l'API "Indicateurs des services d'eau et d'assainissement" sont issues du site SERVICES (Observatoire national des services d'eau et d'assainissement).

Elles portent sur 3 thématiques :

  • les indicateurs de performance des services publics d'eau potable (AEP) avec par exemple les indicateurs nombre d’habitants desservis, prix du service, délai maximal d’ouverture, taux de conformité des eaux distribuées au titre du contrôle sanitaire, rendement du réseau de distribution, indice de pertes en réseau (voir les métadonnées) ;
  • les indicateurs de performance des services publics d'assainissement collectif (AC) avec par exemple les indicateurs nombre d’habitants desservis, quantité de boues, prix du service, taux de desserte, conformités à la directive ERU (voir les métadonnées) ;
  • les indicateurs de performance des services publics d'assainissement non collectif (ANC) avec par exemple les indicateurs nombre d’habitants desservis, taux de conformité (voir les métadonnées).

Les mises à jour du site SERVICE sont intégrées mensuellement à l'API au premier jour du mois.

 

Console de l'API Spécification Swagger                                                              

 

Faites-nous part de vos commentaires sur le forum de contribution Github

 

 

Derniers changements

2018

22/05/2018 : v0.3.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 : ajout dans la réponse de l'attribut api_version (string) : version de l'API (https://semver.org/) 
04/05/2017 : mise à jour de l'adresse de l'API api.hubeau.fr vers hubeau.eaufrance.fr/api/

2016

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 données sont exposées sous la forme d'une API REST.

Les formats supportés sont : JSON, GeoJSON et CSV.

 

Accessibilité

L'API "Indicateurs des services d'eau et d'assainissement" 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 (endpoints)

L'API "Indicateurs des services" permet d'accéder aux indicateurs de performance des services publics d'eau et d'assainissement :

  • communes : retourne les indicateurs de performance des services publics d’eau et d’assainissement par commune (un minimum, maximum et moyenne sont calculés quand il existe plusieurs services publics sur une même commune) ;
  • indicateurs : retourne la liste des valeurs de performance pour un ou plusieurs indicateurs donnés ;
  • services : retourne la liste des indicateurs de performance d’un type de service donné (AEP, AC ou ANC).

 

Exemple

  • Définition de la requête
ExempleParamètreURL 
Accéder aux indicateurs des services de la commune d’Orléans
  • code INSEE commune
hubeau.eaufrance.fr/api/v0/indicateurs_services/
communes?code_commune=45234&size=20&
format=json

Voir le résultat
Accéder aux indicateurs des services des communes du Loiret
  • code INSEE département
hubeau.eaufrance.fr/api/v0/indicateurs_services/
communes?size=20&code_departement=45&
format=json
Voir le résultat
Accéder aux indicateurs des services d’alimentation en eau potable (AEP) de la commune de Marseille
  • code INSEE  commune
  • type de service
hubeau.eaufrance.fr/api/v0/indicateurs_services/
communes?code_commune=13055&size=20&
type_service=AEP&format=json
Voir le résultat
Accéder aux indicateurs des services d’assainissement collectif (AC) du département du Nord pour l’année 2016
  • code INSEE département
  • type de service
  • année
hubeau.eaufrance.fr/api/v0/indicateurs_services/
communes?size=20&code_departement=59&
type_service=AC&annee=2016&format=json
Voir le résultat

 

  • Navigation dans les résultats
DescriptionParamètreURL 
Accéder à la deuxième page de résultats
  • numéro de page
hubeau.eaufrance.fr/api/v0/indicateurs_services/
communes?size=20&page=2&code_departement=59&
type_service=AC&annee=2016&format=json
Voir le résultat

 

  • Sélection des attributs des données obtenues en résultat
DescriptionParamètreURL 
Obtenir le « code service » des services d’eau et d’assainissement
  • fields
hubeau.eaufrance.fr/api/v0/indicateurs_services/
communes?size=20&fields=code_station&page=2&
code_departement=59&type_service=AC&annee=2016&
format=json
Voir le résultat
Obtenir les coordonnées géographiques de la / des communes
  • geometrie
hubeau.eaufrance.fr/api/v0/indicateurs_services/
communes?size=20&fields=code_station&page=2&
code_departement=59&type_service=AC&annee=2016&
geometrie=true&format=json
Voir le résultat

 

Pour identifier l'ensemble des paramètres disponibles sur les opérations, tester dans la console.

 

Console de l'API

 

Dernière mise à jour le 09.08.2018