API Statistics est un service web de requête de données dont les paramètres ne doivent pas respecter un ordre spécifique comparé à l'API SDMX 2.1.
Le Service Web :
fournit les données dans le format JSON-stat 2.0 ;
support uniquement le protocole REST (REpresentation State Transfer) ;
fournit les réponses en anglais, français ou allemand.
Structure de la requête REST
La structure pour construire une requête REST est une URL : {host_url}/{service}/{version}/{response_type}/{datasetCode}?{format}&{lang}&{filters}
Partie URL | Exemple | Commentaire |
|---|---|---|
Partie fixe (fixed part) | ||
{host_url}/ | https://ec.europa.eu/eurostat/api/dissemination/ https://ec.europa.eu/eurostat/api/comext/dissemination (ensembles de données Comext et Prodcom) | Partie fixe de la requête (site web) |
{service}/ | statistics/ | Partie fixe de la requête qui indique le service |
{version}/ | 1.0/ | Partie fixe de la requête qui indique la version |
Partie dynamique (dynamic part) | ||
{response_type}/ | data/ | Seules les données statistiques sont actuellement retournées |
{datasetCode} | nama_10_gdp | Code unique qui identifie les données recherchée (soit un set de données ou une extraction prédéfinie) |
?{format} | ?format=JSON | Paramètre optionel |
&{lang} | &lang=FR | Paramètre optionel |
&{filters} | &time=2019 | Paramètres optionels |
Les paramètres définis dans la requête REST
Les paramètres Filters
Les paramètres Filters (ou filtres) définis dans l’URL sont optionnels. Toutes les dimensions présentes dans le produit de données peuvent être utilisées comme filtre.
Les filtres commencent après le point d’interrogation ("?") dans l’URL. Ils sont séparés par "&" s’il y en a plusieurs.
La structure d’un paramètre filtre : <CODE_DIMENSION>=<VALEUR>
CODE_DIMENSION : le code de la dimension utilisée pour filtrer les données
le code de dimension doit exister dans le produit de données
l’ordre des filtres ne doit pas correspondre à l’ordre des dimensions dans le produit de données
VALEUR: la valeur du filtre est la position dans la dimension, par exemple
time=2019
geo=FR
CODE_DIMENSION et VALEUR peuvent être écrits en minuscule ou en majuscules ; la casse n’a pas d’importance dans l’URL de la requête.
Les paramètres de temps (Time)
Les paramètres "time" et "time_period" sont acceptés dans l’URL. Les deux ciblent la dimension TIME_PERIOD.
D’autres paramètres de temps peuvent être utilisés :
untilTimePeriod – filtre jusqu’à la valeur “TIME_PERIOD” définie
sinceTimePeriod – filtre depuis la valeur “TIME_PERIOD” définie
lastTimePeriod – valeur numérique qui filtre en partant de la fin le nombre de dimensions TIME_PERIOD
Il n’est pas autorisé d’utiliser plus d’un paramètre de temps dans la même requête.
La seule exception est d’utiliser sinceTimePeriod et untilTimePeriod ensemble. Ceci aura pour résultat de filtrer les valeurs sur l’intervalle de temps défini entre les deux valeurs.
Les paramètres de format et de langue
La seule valeur pour le paramètre « format » est "JSON".
Le paramètre de langue (« lang » ) peut avoir une de ces trois valeurs : “EN”, “FR”, ou “DE”. Si le paramètre n’est pas défini, la valeur “EN” est prise par défaut.
Messages d’erreur envoyé en cas de requêtes invalides
Code Erreur | Status HTTP | Description |
|---|---|---|
Erreur client | ||
100 Pas de résultats | 400 Requête incorrecte | Les résultats de la requête est vide. |
100 Pas de résultats | 404 Non trouvé | La ressource demandée n’est pas disponible. |
140 Erreur de syntaxe | 400 Requête incorrecte | La requête est invalide. |
150 Erreur de sémantique | 400 Requête incorrecte | La requête est correcte au niveau syntaxique mais échoue à cause d’une validation sémantique ou un règle métier. |
Erreur serveur | ||
500 Erreur interne du serveur | 500 Erreur interne du serveur | Le service web devrait renvoyer cette erreur quand aucun autre code d’erreur est capable de mieux décrire la cause de l’échec du service à fournir une réponse correcte. Également utilise dans le cas où la requête ne respecte pas la définition du XSD. |
Réponse asynchrone dans le cas de grandes extractions
Quand l’API reçoit une requête, elle détermine si la réponse peut être faite de manière synchrone ou asynchrone.
Dans le cas d’une réponse asynchrone, API renvoit la réponse suivante en JSON :
{"warning":{"status":413, "label":"ASYNCHRONOUS_RESPONSE. Your request will be treated asynchronously. Please try again later."}}
API Statistics ne notifie pas l’utilisateur quand le fichier est prêt, la requête doit être faite une nouvelle fois pour vérifier l’état.