Contexte
Cette page liste des exemples de requêtes de données via des liens API afin de récupérer des données de manière récurrente.
Quand un utilisateur répète un ou plusieurs téléchargement dans l'interface du Data Browser, il pourrait plutôt l'automatiser avec une solution de son choix basé sur un script.
Voici ci-dessous quelques exemples pour inspiration. La même logique peut être appliqué dans d'autre langage de script.
Exemple 1 : télécharger périodiquement un petit nombre d'ensemble de données
Cela s'effectue en 2 étapes:
- préparer une liste d'ensembles de données
- exécuter le script approprié en PowerShell pour effectuer le téléchargement.
Etape 1 : obtenir la liste (filtrée) d'ensemble de données
Cette étape permet d'obtenir un fichier nommé Filtered_Items_List_FR.txt au format texte séparé par des tabulations. Voir la description détaillé du fichier
Ce type de fichier est facile d'utilisation dans les langages de programmation.
Pas à pas :
- Aller dans l'interface de Téléchargements du Data Browser
- Sélectionner des ensembles de données. Dans cet exemple : AACT_ALI01 et AACT_EAA01
- Dans 'Opérations de masse’, sélectionner ‘Télécharger la liste des éléments sélectionnés (.txt)’ comme montré dans la capture d'écran ci-dessous
- En résulte une archive zip content un fichier nommé Filtered_Items_List_FR.txt.
- Ne pas oublier d'extraire le fichier de l'archive et le sauvegarder par exemple dans le dossier utilisateur ‘C:\Users\your user name\Filtered_Items_List_FR.txt’.
- Exemple :
- Télécharger un fichier d'exemple avec la liste des ensembles de données de la capture d'écran ci-dessus.
La liste complète des ensembles de données peut être téléchargé avec l'action ‘Télécharger la liste des éléments (.txt)’ comme utilisé dans les exemples suivants.
Etape 2 : télécharger des fichiers de données
Maintenant que la liste est prête, le script ci-dessous doit être exécuter dans une console Windows PowerShell. Cette outil doit être disponible par défaut sur la plupart des PC en version 5 et disponible sur les autres plateformes depuis la version 7.
Executer une commande powershell sous Windows
- Pour ouvrir une console, utiliser la recherche de Windows, saisir "PowerShell" et démarrer l'application.
- Copier / coller le script ci-dessous dans la console PowerShell et appuyer sur la touche 'Entrée‘ pour l'exécuter.
- En résultat, deux fichiers (selon l'exemple ci-dessus) sont écrit dans le dossier courant qui est par défaut le dossier utilisateur ‘C:\Users\<nom_utilisateur>’
Pour plus d'information, merci de consulter la documentation de PowerShell
2.1 Télécharger des fichiers non-compressés
En connectant quelques "cmdlets" (Import-CSV, ForEach-Object and WebClient.DownloadFile), il est facile de télécharger dans le dossier courant le contenu voulu à partir d'une URL (SDMX-CSV dans cet exemple).
Import-CSV .\Filtered_Items_List_FR.txt -Delimiter "`t" | ForEach-Object { (New-Object System.Net.WebClient).DownloadFile($_."URL pour le téléchargement des données (csv)", "$pwd\$($_.Code).csv") }
Cet exemple utilise les colonnes Code et "URL pour le téléchargement des données (csv)".
En adaptant le script, il est possible de télécharger un autre format proposé dans le fichier ‘Filtered_Items_List_FR.txt’ :
- URL pour le téléchargement des données (tsv)
- URL pour le téléchargement des données (sdmx)
2.2 Télécharger des fichiers compressés
Pour réduire l'utilisation de bande passante et d'espace disque, il est possible d'obtenir des fichiers GZ-compressed en ajoutant le paramètre &compressed=true à l'URL
Le script ci-dessous étend l'exemple précédent de récupération de données au format SDMX-CSV pour les obtenir dans un format compressé GZIP.
Import-CSV .\Filtered_Items_List_FR.txt -Delimiter "`t" | ForEach-Object { (New-Object System.Net.WebClient).DownloadFile("$($_."URL pour le téléchargement des données (csv)")&compressed=true", "$pwd\$($_.Code).csv.gz") }
2.3 Télécharger des fichiers compressés puis les décompresser localement
Même si il est nécessaire d'obtenir un fichier décompressé, il reste possible d'optimiser le téléchargement en utilisant une fonction PowerShell pour décompresser les fichiers reçus.
# from https://securitytidbits.wordpress.com/2017/04/14/powershell-and-gzip-compression/comment-page-1/ Function Gunzip-File([ValidateScript({Test-Path $_})][string]$File){ $srcFile = Get-Item -Path $File $newFileName = Join-Path -Path $srcFile.DirectoryName -ChildPath $srcFile.BaseName try { $srcFileStream = New-Object System.IO.FileStream($srcFile.FullName,([IO.FileMode]::Open),([IO.FileAccess]::Read),([IO.FileShare]::Read)) $dstFileStream = New-Object System.IO.FileStream($newFileName,([IO.FileMode]::Create),([IO.FileAccess]::Write),([IO.FileShare]::None)) $gzip = New-Object System.IO.Compression.GZipStream($srcFileStream,[System.IO.Compression.CompressionMode]::Decompress) $gzip.CopyTo($dstFileStream) } catch { Write-Host "$_.Exception.Message" -ForegroundColor Red } finally { $gzip.Dispose() $srcFileStream.Dispose() $dstFileStream.Dispose() } } Import-CSV .\Filtered_Items_List_FR.txt -Delimiter "`t" | ForEach-Object { (New-Object System.Net.WebClient).DownloadFile("$($_."URL pour le téléchargement des données (csv)")&compressed=true", "$pwd\$($_.Code).csv.gz") Gunzip-File "$pwd\$($_.Code).csv.gz" Remove-Item "$pwd\$($_.Code).csv.gz" }
Exemple 2 : télécharger périodiquement une grande liste d'ensemble de données
Cet exemple est semblable au précédent mais la sélection des ensembles de données se fait dans le script au lieu de se faire manuellement dans l'interface du Data Browser.
Ce script se base sur le fichier obtenu via l'action ‘Télécharger la liste des éléments (txt)’.
Précondition : avoir la liste complète des ensembles de données
Il est possible dans une requête de téléchargement Data Browser, d'obtenir la liste complète des éléments,
Il y aura dans l'archive un fichier nommé Full_Items_List_FR.txt qui contient des valeurs séparées par tabulation. C'est le même format que le fichier utilisé dans l'exemple précédent.
Exécution : selectionner et télécharger des fichiers de données
Pour définir les ensembles de données à télécharger, il est possible d'appliquer une condition dans le script. Dans l'exemple ci-dessous, tous les ensembles de données commençant par TPS seront téléchargés en une seule exécution.
Import-CSV .\Full_Items_List_EN.txt -Delimiter "`t" | ForEach-Object { If($_.Code.StartsWith("TPS")) { # download only TPS datasets (New-Object System.Net.WebClient).DownloadFile($_."Data download url (csv)", "$pwd\$($_.Code).csv") } }
Ce script est à modifier par la suite en fonction des besoins.
Merci de vérifier avant exécution que
- une condition est bien appliqué dans le script quand le fichier d'entrée est le fichier Full_Items_List_FR.txt
- l'option de compression est utilisé pour les requêtes lourde en ressources
Dans le cas contraire, tous les ensemble de données Eurostat seraient téléchargés, ce qui serait couteux en espace disque.
Exemple 3 : garder une copie d'un ensemble de données à jour avec Node.js
Pour savoir qu'un ensemble de données a été mis à jour, l'information est disponible dans la page produit de l'ensemble de données (par exemple pour TPS00001), dans la liste de l'interface "Téléchargements" (voir exemple 1) ou dans la table des matières (table_of_content.xml).
Un autre moyen consiste à obtenir cette information en interrogeant via l'API le Dataflow SDMX associé à l'ensemble de données. Cet élément est disponible en deux formats:
- SMDX-ML: https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1/dataflow/ESTAT/TPS00001
- JSON-STAT : https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1/dataflow/ESTAT/TPS00001?format=JSON
Comme le format JSON-STAT est un objet JSON valide, son utilisation est très simple pour les utilisateurs familier de Javascript / Node.js
Cet exemple propose un script Node.js pour télécharger un fichier de donnée à la condition qu'une mise à jour soit disponible depuis la dernière exécution.
Pour exécuter ce script, il est nécessaire :
- d'avoir Node.js installé sur l'ordinateur
- d'avoir sauvegarder le script ci-dessous dans un fichier
- d'exécuter le script comme mentionné dans la page https://nodejs.dev/fr/learn/run-nodejs-scripts-from-the-command-line/
#!/usr/bin/env node // library to make HTTP calls const fetch = require('node-fetch'); // library to write to the filesystem const fs = require('fs'); //util method to write to the filesystem const downloadFile = (async (url, path) => { const res = await fetch(url); const fileStream = fs.createWriteStream(path); await new Promise((resolve, reject) => { res.body.pipe(fileStream); res.body.on("error", reject); fileStream.on("finish", resolve); }); }); //last time program was run (you should change this value or make it a parameter of your script) const lastCheck = '2020-09-19T18:00'; // online data code to lookup (you should change this value or make it a parameter of your script) const onlineDataCode = "T2020_10"; (async () => { //retrieve information on dataset in JSON const response = await fetch('https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1/dataflow/ESTAT/' + onlineDataCode + '?format=json'); const json = await response.json(); //extract last data udpate date var lastUpdateDate = null; for (var i = 0 ; i < json.extension.annotation.length; i++) { //console.log(json.extension.annotation[i]); if (json.extension.annotation[i].type == "UPDATE_DATA") lastUpdateDate = json.extension.annotation[i].date; } //compare last data update date with our own if (Date.parse(lastUpdateDate) > Date.parse(lastCheck)) { console.log(onlineDataCode + " need update " + " last updated at " + lastUpdateDate); //download needed format (remove the line you do not need) console.log("Downloading data in TSV for " + onlineDataCode ); downloadFile('https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1/data/' + onlineDataCode + '?format=TSV', onlineDataCode +'.tsv'); console.log("Downloading data in SDMX-CSV for " + onlineDataCode ); downloadFile('https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1/data/' + onlineDataCode + '?format=SDMX-CSV', onlineDataCode +'.sdmx.csv'); console.log("Downloading data in SDMX-ML 2.1 for " + onlineDataCode ); downloadFile('https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1/data/' + onlineDataCode , onlineDataCode +'.sdmx.xml'); console.log("Downloading structure in SDMX-ML 2.1 for " + onlineDataCode ); downloadFile('https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1/dataflow/ESTAT/' + onlineDataCode +'?references=descendants&details=referencepartial', onlineDataCode +'.sdmx.structure.xml'); // or extract specific time-series in json-stat to feed visualisations.. downloadFile('https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1/data/' + onlineDataCode + '/A.....FR+LU+DE?format=JSON', onlineDataCode +'_FR_LU_DE.json'); // or use Eurostat statistics query format, because SDMX REST have may be less readable depending the query (may have too many dots, need to know the order of dims) downloadFile('https://ec.europa.eu/eurostat/api/dissemination/statistics/1.0/data/' + onlineDataCode + '?geo=FR&geo=LU&geo=DE', onlineDataCode +'_FR_LU_DE.stats.json'); } else { console.log(onlineDataCode + " already up to date " + " last updated at " + lastUpdateDate); } })();