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.

Des changements sur l'API sont survenus depuis le 2024-05-29, consultez le changelog (en bas de cette page). L'API reste compatible avec l'ancienne version mais les anciens champs ne permettront pas de récuperer les nouveaux jeux de données publiés dans le futur.
Nous avons du mettre en place des limites d'usage plus restrictives afin de préserver la qualité de service de nos serveur. Nous vous invitons à limiter les requêtes à cette API notamment en utilisant l'identifiant de version de publication des jeux de données /version. La fréquence de mise à jour est hebdomadaire pour la plupart des données (sinon annuelle).

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 étendues (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.

Politique de mise à jour des donnés

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 et peut être plus précoce en période de faible activité)
  • 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.

La mise à jour des données est marqué par un changement de l'identifiant de version de la ressource /version de l'API.

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, nos données 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 :

  • PAY correspond au niveau national (métropole) (niveau NUTS 0)
  • RDD correspond au Région (découpage après 2016, niveau NUTS 1)
  • 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 /indicators

La ressource /indicators retourne un document json contenant une liste dont chaque élement décrit un indicateur disponible et les dimensions utilisables pour celui-ci. Notamment
  • l'identifiant propre à chaque indicateur (champs id)
  • la définition de l'évènement de santé sujet de cet indicateur de surveillance, les dates de la collecte
  • la liste des jeux de données disponibles (champs datasets), chacun correspondant à un ensemble de dimensions fixées (période temporelle, niveau géographique, ...)

Dernière semaine et année disponibles

Deux ressources permettent d'obtenir

  • /lastweek dernière semaine disponible pour les indicateurs hedbomadaires
  • /lastyear dernière année disponible pour les données annuelles (*).
* Pour les données annuelles, certains indicateurs peuvent bénéficier d'une publication anticipée, elle sera indiquée dans la période de surveillance de la resource décrivant cet indicateur.

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 qualité de service de cette API, Il est fortement recommendé 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. Un usage de téléchargement continu des donné ou excessif pourra donner lieu à un blocage des IP concernées.

Exemples

Récupération de la version de la base /version

curl https://www.sentiweb.fr/api/v1/datasets/rest/version 
1611650941

A noter s'il s'agit actuellement d'un nombre, il ne faut pas lui accorder une significaction particulière. La représentation de la version pourra être modifiée às tout moment vers un code alphanumérique ([A-Za-z0-9]+). Si la valeur renvoyée par cette ressource est différente alors la base a été modifiée.

Cet identifiant de version est par contre atomique sur l'ensemble des fichiers de données publiés par cette API.

Récupération de la description des indicateurs disponibles /indicators

curl -H "Accept: application/json" https://www.sentiweb.fr/api/v1/datasets/rest/indicators

Les réponses sont encodées en UTF-8 mais les champs textes (comme la définition des indicateurs) peuvent contenir des entitées HTML

[
{
    "id": "3",
    "case_definition": "Fièvre supérieure à 39°C, d'apparition brutale, accompagnée de myalgies et de signes respiratoires.",
    "geo": ["PAY", "REG","RDD"],
    "periods": [
        {
            "frequency": "week",
            "start": 198444,
            "end": 0
        }
    ],
    "ongoing": false,
    "datasets": [
            {
                "id": "inc-3-PAY",
                "geo": "PAY",
                "datasource": "rs",
                "time_scale": "week",
                "spans": [  "all", "short", "last"],
                "formats": ["json", "csv"],
                "time_period": {
                    "frequency": "week",
                    "start": 198444,
                    "end": 202410
                }
            },
            {
                "id": "inc-3-RDD",
                "geo": "RDD",
                "datasource": "rs",
                "time_scale": "week",
                "spans": ["all", "short", "last"],
                "formats": [ "json", "csv"],
                "time_period": {
                    "frequency": "week",
                    "start": 198444,
                    "end": 202410
                }
            }
        ]
    },
    ...
 ]

Récupération d'un dataset (ressource disponible depuis le 29/05/2024) /dataset

La nouvelle operation permet de récupérer un dataset depuis son id (champs "id" du tableau "datasets" décrivant chaque indicateur

Paramètres

  • id : identifiant d'un dataset (ex: 'inc-3-PAY')
  • span: étendue du jeu de données (ex: short, all, last)
  • $format (optional): format de données, (json, csv) (prend en charge également l'entête HTTP Accept avec le MIME type correspondant)
curl -H "Accept: text/csv" https://www.sentiweb.fr/api/v1/datasets/rest/dataset?id=inc-3-PAY&span=short

Récupération des données d'incidence (exemple des syndromes grippaux, national) /incidence

Attention la ressource /incidencene prendra pas en charge les nouveaux datasets que nous pourrions publier par la suite avec de nouvelles dimensions (source de données, groupage, etc). Seule les jeux de données d'incidence déjà publiées jusqu'à présent pourront être récupérés via cette ressource. Utilisez la ressource /dataset pour avoir accès à tous les jeux de données;

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 (les jeux de données disponible pour chaque indicateur sont disponible dans le champs 'datasets' de la resource 'indicators')
  • $format : Format de données (peut également être définit par le MIME type via 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,202410],"geo":["PAY",0],"geo_ref":"insee","indicator":"3","type":"all","conf_int":true,"compact":false,"age_group":false,"span":"all"},"date":"2024-03-13T17:02:59+01:00","bundle":"1710342350"}
week,indicator,inc,inc_low,inc_up,inc100,inc100_low,inc100_up,geo_insee,geo_name
202410,3,68407,58929,77885,103,89,117,FR,France
202409,3,72033,63663,80403,108,95,121,FR,France
202408,3,104566,94520,114612,157,142,172,FR,France
202407,3,138078,127050,149106,207,190,224,FR,France
202406,3,190062,177955,202169,285,267,303,FR,France
202405,3,216237,203595,228879,324,305,343,FR,France
202404,3,213196,200547,225845,320,301,339,FR,France
202403,3,163457,152276,174638,245,228,262,FR,France
202402,3,129436,119453,139419,194,179,209,FR,France
202401,3,120769,109452,132086,181,164,198,FR,France
202352,3,115446,103738,127154,174,156,192,FR,France
202351,3,148755,136546,160964,224,206,242,FR,France
202350,3,147971,136787,159155,223,206,240,FR,France
202349,3,147552,136422,158682,222,205,239,FR,France
202348,3,124204,113479,134929,187,171,203,FR,France
202347,3,110910,100658,121162,167,152,182,FR,France
202346,3,83853,75096,92610,126,113,139,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.

De manière générale, il est préférable de limiter le nombre de requête au maximum afin de préserver la qualité de notre service. L'usage d'un stratégie de cache basée sur la version de notre base est fortement recommendée pour ne pas télécharger à nouveau des fichiers qui n'auraient pas changé

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 entêtes sont prefixées de "X-" ces entêtes 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

Status de dépassement des limites et blocage

En cas de dépassement des limites d'usage, le serveur émettera une réponse portant le status 429 jusqu'à la fin de la fenêtre considérée.

Des requêtes persistant après dépassement de la limite peuvent aboutir au blocage de l'IP concernée pour une durée de plusiers jours. L'entête X-RateLimit-Reset dépassera dans ce cas la fênetre en indiquant la fin de la période de blocage.

Changements survenus sur ce service (les types évoqués sont décrits dans la documentation technique de l'API)

29/05/2024
  • Le champs geo_name d'IncidenceRecord est déprécié, il ne sera plus disponible dans les jeux de données rajoutés dans le futur. Le champs geo_insee contient le numéro insée de la subdivision géographique concernée, un jeu de données contenant les correspondances est disponible à files/geolevels.json
  • le champs periods de la ressource Indicator est déprécié pour un nouveau champs datasets
  • Ajout d'un nouveau champs datasets ŕ la ressource Indicator qui décrit précisément les jeux de données disponibles pour chaque indicateur en incluant la période, le niveau géographique, les formats et les étendues ('span') disponibles
  • Nouvelle ressource /dataset permettant de récupérer un jeu de données par son id
08/06/2023
  • Reintegration de geo_name au type IncidenceRecord pour une compatibilité avec l'ancienn format de fichier