API Sentiweb
Nous proposons une API REST permettant un accès direct au téléchargement de nos jeux de données
Une documentation technique est disponible décrivant les actions disponibles etla structure des réponses.
Données disponibles
L'API permet de télécharger les incidences et taux d'incidence pour les indicateurs en cours de surveillance.
Pour les méthodes de collecte et de calculs nous vous renvoyons vers les pages méthodes de ce site.
Les données publiées sont organisées selon plusieurs axes :
- Indicateur : Indicateur de santé proposé par le réseau Sentinelles. Il s'agit de l'évenement de santé observé par les médecins Sentinelles. Chaque indicateur utilise une définition de cas, indiquant aux médecins les critères d'inclusion ou d'exclusion.
- Temporelle : Selon l'indicateur les données proposées seront disponible à l'échelle hebdomadaire ou annuelle (voir le paragraphe Métadonnées concernant les informations décrivant les indicateurs)
- Géographiques : National, régional (découpage pré-2016 et "nouvelles" régions)
Taille des jeux de données
Les jeux de données hebdomadaires sont disponibles en plusieurs envergures (span) couvrant des périodes plus ou moins longues
- 'all' : Tout l'historique (par défaut)
- 'short' : Période de temps récente (10 dernières semaines)
- 'last' : Dernière valeur uniquement
Nous vous invitons à n'utiliser que le jeux de données correspondant à vos besoins afin de limiter la taille des téléchargements.
Représentation des données
Semaine
Les numéros de semaine sont calculés selon l'ISO 8601 et représenté au format 'YYYYWW' (facilement manipulable numériquement, équivalent au format '%G%V' strftime, l'année et la semaine sont respectivement le dividende et le reste de la division par 100 de cette valeur).
L'année d'un numéro de semaine peut être différente des jours qui la composent (par exemple la semaine 53 de l'année 2020, '202053', contient le 1er janvier 2021).
Zones géographiques
Les zones géographiques sont identifiées par les codes issus du Code Officiel Géographique de l'INSEE. A noter que le code 'FR' n'inclut pas de données sur les DOM et TOM le réseau Sentinelles ne couvrant que la métropole. Les taux d'incidence sont calculés sur la population métropolitaine annuelle (celle ci a pu être basée sur différentes sources de données depuis 1984, depuis 2015 nous utilisons la population légale disponible la plus récente pour chaque nouvelle année).
L'identification des niveaux géographiques utilise une nomenclature interne :
- La valeur 'PAY' correspond au niveau national (métropole) (niveau NUTS 0)
- La valeur 'RDD' correspond au Région (découpage après 2016, niveau NUTS 1)
- La valeur 'REG' correspond au Région (découpage avant 2016, niveau NUTS 2)
Le libellé de la zone est &ecute;galement fourni dans certains jeux de donnés à titre indicatif pour faciliter la lecture (par un humain) des fichiers. Il ne doit pas être utilisé comme identifiant d'une zone, il peut être modifié à tout moment, sans préavis.
Metadonnées
L'API expose àgalement des jeux de métadonnées permettant de décrire les données disponibles
Indicateurs
La resource Indicateurs décrit chaque indicateur disponible et les axes utilisables pour ceux ci. Vous y trouverez notamment l'identifiant propre à chaque indicateur- Les indicateurs de santé notamment la définition de l'évènement de santé sujet de la surveillance, les dates de la collecte ainsi que les niveaux géograhiques et temporelles de données disponibles
- Les zones géographiques disponibles (découpage et hierarchie)
Dernière semaine et année disponibles
Deux resources permettent d'obtenir
- la dernière semaine disponible pour les indicateurs hedbomadaires
- la dernière année disponible pour les données annuelles (*).
Politique de mise à jour des données
La mise é des données est effectuée regulièrement en suivant
- Pour les données hebdomadaires : la publication du bulletin hebdomadaire, qui a lieu à partir du mercredi après midi (l'heure est sujet à variation notamment en période de forte activité épidémique)
- Pour les données annuelles : les données sont mises à jour avec la publication du bilan annuel de l'année précédente (publié entre juin et septembre de l'année suivante)
Les date et heure de mise à jour peuvent être sujet à variation selon les contraintes de production et de validation de ces données.
Usage
Mise à jour et version de publication
L'API expose un identifiant de version de la mise à jour des jeux de données (la mise à jour est conjointe pour l'ensemble des jeux de données). Une mise à jour des données impliquera un changement de cet identifiant de version.
Afin de préserver la bande passante de cette API, Il est fortement conseillé de mettre en place des stratégies limitant le téléchargement des données au strict nécessaire, notamment en utilisant cet identifiant de version pour détecter une éventuelle mise à jour des données et déclencher un nouveau téléchargement.
Exemples
Récupération de la version de la base
curl https://www.sentiweb.fr/api/v1/datasets/rest/version
1611650941
A noter s'il s'agit actuellement d'un nombre mais il ne faut pas lui accorder une significaction particulière. La représentation de la version peut être modifiée às tout moment. Si la valeur renvoyée par cette resource est différente alors la base a été modifiée.
Cette version est par contre atomique sur l'ensemble des fichiers de données.
Récupération de la description des indicateurs disponibles
curl -H "Accept: application/json" https://www.sentiweb.fr/api/v1/datasets/rest/indicators
[
{
"id": "0",
"case_definition": "Tout acte délibéré réalisé dans l'intention de se donner la mort : geste de violence sur sa propre personne (phlébotomie, précipitation, pendaison, arme à feu, intoxication au gaz ...) ou ingestion d'une substance toxique ou de médicaments à une dose supérieure à la dose reconnue comme thérapeutique. Cet acte doit être inhabituel : les conduites addictives (alcool, drogues...) sont donc exclues ainsi que les automutilations répétées et les refus de s'alimenter.",
"geo": [ "PAY" ],
"periods": [
{
"frequency": "year",
"start": 1999,
"end": 0
}
],
"ongoing": true
},
{
"id": "6",
"case_definition": "Au moins 3 selles liquides ou molles par jour datant de moins de 14 jours motivant la consultation.",
"geo": ["PAY", "REG", "RDD"],
"periods": [
{
"frequency": "week",
"start": 199049,
"end": 0
}
],
"ongoing": true
},
...
]
Récupération des données d'incidence (exemple des syndromes grippaux) (national)
Paramètres
- indicator : Code identifiant l'indicateur à télécharger (IRA, varicelle, etc), celui ci est indiqué dans les métadonnées des indicateurs
- span : Envergure du jeu de données ('all', 'short', 'last'), par défaut 'all'
- geo : Niveau géographique des données. Les niveaux disponibles varient par indicateur (indiqué dans les métadonnées de chaque indicateur)
- $format : Format de données (peut également être fournit par l'entête HTTP Accept
Toutes les donnnées, en CSV
curl -H "Accept: text/csv" https://www.sentiweb.fr/api/v1/datasets/rest/incidence?indicator=3&geo=PAY&span=all
Il est àgalement possible d'utiliser le paramètre spécial '$format' pour requérir un format particulier ('csv', 'json')
curl https://www.sentiweb.fr/api/v1/datasets/rest/incidence?indicator=3&geo=PAY&span=all&$format=csv
Nos fichiers CSV contiennent une première ligne de commentaire ceci afin que le contenu du fichier reste associé à ses métadonnéees. La plupart des logiciels permettant de lire les fichiers csv peuvent le prendre en charge (par exemple en R) bien que la ligne de commentaire ne soit pas dans la norme décrivant le format csv.
# @source="réseau Sentinelles, INSERM, Sorbonne Université, https://www.sentiweb.fr", @meta={"period":[198444,202103],"geo":["PAY",1],"geo_ref":"insee","indicator":"3","type":"all","conf_int":true,"compact":false,"age_group":false}, @date=2021-06-18T18:32:25+02:00, bundle=1611650941
week,indicator,inc,inc_low,inc_up,inc100,inc100_low,inc100_up,geo_insee,geo_name
202103,3,28139,22926,33352,43,35,51,FR,France
202102,3,18010,14474,21546,27,22,32,FR,France
202101,3,21809,17786,25832,33,27,39,FR,France
202053,3,21220,16498,25942,32,25,39,FR,France
202052,3,16428,12285,20571,25,19,31,FR,France
202051,3,21619,17370,25868,33,27,39,FR,France
202050,3,16845,13220,20470,26,20,32,FR,France
202049,3,12939,9923,15955,20,15,25,FR,France
202048,3,13804,10641,16967,21,16,26,FR,France
202047,3,19085,15285,22885,29,23,35,FR,France
202046,3,24801,20503,29099,38,31,45,FR,France
Uniquement les 10 dernières semaines
Les données d'incidence sont disponibles avec trois niveaux de recul temporel : toutes les données 'all', les 10 dernières semaines 'short', et 'last' comprenant uniquement la dernière semaine
Utilisez les données correspondant au mieux à votre usage afin de préserver notre bande passante.
curl https://www.sentiweb.fr/api/v1/datasets/rest/incidence?indicator=3&geo=PAY&span=short&$format=csv
Conditions d'utilisation du service
Le service est disponible en respectant les limites d'usage, définis par un nombre de requêtes par période d'un certains nombre de secondes.
Les limites applicables dépendent de la charge de nos serveurs et sont modifiables à tout moment. Elles sont indiquées dans les entêtes en réponse à une requête. Il est fortement recommandé qu'un client réalisant des requêtes répétées à nos services prennent en compte ces limites pour adapter le rythme de ces requêtes.
Entêtes RateLimit
Des entêtes dans la réponse à une requête sont fournies afin de permettre aux clients de s'adapter
Elles suivent la préparation du standard de l'IETF. Les nom des entetes sont prefixées de "X-" ces entetes n'étant pas encore standards
X-RateLimit-Limit: Nombre de requêtes maximale possibles sur la fenêtre.X-RateLimit-Remaining: Nombre de requêtes restante sur la fenêtre.X-RateLimit-Reset: Nombre de secondes restantes dans la fenêtre actuelle.X-RateLimit-Policy: Description de la politique de limite actuelle (voir le draft de l'IETF ci dessus), indiquant la limite et la taille de la fenêtre (w) en secondes