diff --git a/03_Fiches_thematiques/Fiche_api.qmd b/03_Fiches_thematiques/Fiche_api.qmd index f5312e3e..ec2f71e4 100644 --- a/03_Fiches_thematiques/Fiche_api.qmd +++ b/03_Fiches_thematiques/Fiche_api.qmd @@ -6,11 +6,12 @@ L'utilisateur souhaite accéder à des données _via_ une API. ## Tâche concernée et recommandation - En premier lieu, il est recommandé de vérifier s'il existe un _package_ `R` spécifique à l'API que vous voulez utiliser. -- S'il n'existe de _package_ spécifique,il est recommandé d'utiliser -le _package_ `httr` pour transmettre des requêtes à l'API et le _package_ `jsonlite` pour retravailler le résultat des requêtes afin de la transformer dans un format plus exploitable. +- S'il n'existe de _package_ spécifique, il est recommandé d'utiliser +le _package_ `httr2` pour transmettre des requêtes à l'API, [le package httr est désormais déprécié](https://cran.r-project.org/web/packages/httr/readme/README.html) +- `httr2` permet nativement de gérer la transformation des retours au format JSON, mais au besoin pour des cas complexes le _package_ `jsonlite` peut être nécessaire - Pour accéder à des données disponibles sur le site , -il est recommandé d'utiliser l'un des _packages_ suivants : `doremifasol`, `insee`, `inseeLocalData`. Le _package_ `apinsee` permet de gérer le renouvellement des jetons de connexion. -- Les jetons d'accès (*token*) doivent être utilisés sous forme de variable d'environnements, inscrits dans un fichier `.Renviron` qui n'est pas partagé. +il est recommandé d'utiliser l'un des _packages_ suivants : `doremifasol`, `melodi` (catalogue de données Melodi), `insee` (séries BDM). +- Si nécessaire, les jetons d'accès (*token*) doivent être utilisés sous forme de variable d'environnements, inscrits dans un fichier `.Renviron` qui n'est pas partagé. - Si l'accès à internet se fait par l'intermédiaire d'un proxy, sous Windows, il est recommandé d'utiliser la fonction `curl::ie_get_proxy_for_url`. ::: @@ -49,7 +50,7 @@ Une API peut souvent être utilisée de deux façons : par une interface Web, et ## Spécificité Insee Les API mises à disposition des utilisateurs par l'Insee se trouvent dans le -[catalogue des API](https://api.insee.fr/catalogue/). +[catalogue des API](https://portail-api.insee.fr/). ::: #### Consulter l'interface Web d'une API @@ -72,8 +73,10 @@ consultation ou pour réaliser du téléchargement de masse. De plus, l'interfac Le mode principal de consultation d'une API consiste à adresser une requête à cette API _via_ un logiciel adapté (`R`, `Python`, `Java`...). Comme pour l'utilisation d'une fonction, l'appel d'une API comprend des paramètres qui sont détaillées dans la documentation de l'API. Voici les éléments importants à avoir en tête sur les requêtes : -- Le **point d'entrée** d'un service offert par une API se présente sous la forme d'une URL (adresse web). Chaque service proposé par une API a sa propre URL. Par exemple, dans le cas de l'API Sirene, l'URL à utiliser pour obtenir des informations sur un Siren est : -. +- Le **point d'entrée** d'un service offert par une API se présente sous la forme d'une URL (adresse web). +Chaque service proposé par une API a sa propre URL. Par exemple, dans le cas de l'API Sirene, +l'URL à utiliser pour obtenir des informations sur un Siren est : +. - Cette URL doit être complétée avec différents paramètres qui précisent la **requête** (par exemple l'identifiant Siren). Ces paramètres viennent s'ajouter à l'URL (qui peut donc devenir très longue!). Chaque service proposé par une API a ses propres paramètres, détaillés dans la documentation. S'agissant de l'API Sirene, l'utilisateur intéressé peut retrouver dans la documentation le paramétrage de l'URL. @@ -93,84 +96,25 @@ Dans certains cas, des _packages_ spécifiques à une API ont été créés pour Nous allons voir ici quelques _packages_ permettant de traiter l'information d'une API facilement : -### Le _package_ [apinsee](https://github.com/InseeFrLab/apinsee) - -Ce _package_ est très utile pour l'utilisation des API mises à disposition sur -le catalogue des API. En effet, pour ces API, pour pouvoir effectuer une requête, -il est nécessaire de s'authentifier à différents niveaux : - -1. S'authentifier grâce à une clé personnelle, associée à un compte créé -sur ; -2. Avoir un jeton d'accès temporaire. Ces jetons ont une durée de vie -limitée et doivent régulièrement être renouvelés. - -Ce _package_ propose de générer facilement un jeton d'accès temporaire à partir de `R`. De cette façon, il n'y a plus besoin de naviguer entre le programme `R` -et le catalogue des API pour renouveler un jeton. - -Pour utiliser cette fonctionnalité, il faut configurer l'usage du _package_ lors de la première utilisation. Plus précisément, il faut renseigner les variables d'environnement `INSEE_APP_KEY` et -`INSEE_APP_SECRET` dans le fichier de configuration `.Renviron` de `R`. (voir la fiche [Personnaliser la configuration de `R`] pour une présentation détaillée des fichiers de configuration de `R`). Pour le faire, il suffit d'exécuter la commande suivante : - -```{r, eval = FALSE} -usethis::edit_r_environ("user") -``` - -Votre fichier `.Renviron` est alors ouvert par RStudio s'il existe déjà. Si le fichier `.Renviron` n'existe pas encore, il est automatiquement créé (vide), enregistré et ouvert -par `RStudio`. Il convient d'y ajouter deux variables d'environnement, `INSEE_APP_KEY` et -`INSEE_APP_SECRET`. Les lignes suivantes peuvent servir de modèle, en -remplaçant la deuxième partie de chaque ligne par la clé du compte à utiliser : - -~~~markdown -# clef du consommateur -INSEE_APP_KEY=xxxxxxxxxxxxxxxxxx -# secret du consommateur -INSEE_APP_SECRET=yyyyyyyyyyyyyyyyyy -~~~ - -::: {.callout-note} -Voici deux remarques sur le stockage des variables d'environnement : - -- L'option `"user"` dans l'utilisation de la fonction `usethis::edit_r_environ()` -permet de stocker ces clés dans un fichier global, connu -de tous les projets d'un utilisateur `R`. Cela évite, d'une part, de stocker -la même information à deux endroits différents. D'autre part, cela évite -d'associer des informations personnelles à un projet, qui doit être sous contrôle -de version (voir la Fiche [Utiliser R avec RStudio](#git)) car -le fichier `.Renviron` est un fichier contenant des informations personnelles. - -- Si vous avez choisi l'option `"project"` lors de -l'appel à `usethis::edit_r_environ`, il faut ajouter le `.Renviron` dans -les fichiers à ne pas suivre avec `Git` grâce à la commande suivante : +### Le _package_ [doremifasol](https://inseefrlab.github.io/DoReMIFaSol) -```{r, eval = FALSE} -usethis::edit_git_ignore(".Renviron") -``` -::: +Ce _package_ permet d'importer facilement dans R des données mises à disposition par différents canaux sur le site de l'Insee. -Enfin, pour créer le token temporaire, il suffit d'exécuter : +Il permet entre autres de solliciter l'API Sirène dans une procédure de requêtage intégrée. +Pour cela, il faut au préalable avoir configuré un accès à l'API REST de l'Insee et passer en variable d'environnement le jeton d'authentification. +Pour obtenir ce jeton, la procédure est expliquée par exemple [ici](https://static.insee.fr/api-sirene/Insee_API_publique_modalites_connexion.pdf) +ou encore [là](https://portail-api.insee.fr/catalog/api/2ba0e549-5587-3ef1-9082-99cd865de66f/doc?page=85c5657d-b1a1-4466-8565-7db1a194667b). +Une fois cela réalisé, on insère dans la variable d'environnement `INSEE_API_TOKEN` le jeton obtenue, +par exemple en insérant la ligne suivante dans le fichier `.Renviron` (en remplaçant `xxxxxxxx` par la valeur du jeton) : -```{r, eval = FALSE} -token <- apinsee::insee_auth() ``` - -Ce token peut ensuite être utilisé comme valeur du paramètre token de -la fonction `httr::config()` qui sert à contrôler les paramètres d'une requête -vers internet faite par `R` - -```{r, eval = FALSE} -library(httr) -set_config(config(token = token)) +INSEE_API_TOKEN='xxxxxxxx' ``` -Dès lors, vous pouvez accéder aux API de -l’Insee auxquelles votre application a souscrit. +Il reste ensuite à préciser le type d'information souhaitée (unités légales, établissements...) et la requête via l'argument `argsApi`. - -### Le _package_ [doremifasol](https://inseefrlab.github.io/DoReMIFaSol) - -Ce _package_ permet entre autres de solliciter l'API Sirène dans une procédure de requêtage intégrée. - -`doremifasol` s'appuie sur le _package_ `apinsee`, il faut donc renseigner les variables d'environnement décrites ci-dessus. Il reste ensuite à préciser le type d'information souhaitée (unités légales, établissements...) et la requête via l'argument `argsApi`. Par exemple, pour lister tous les bouchers de la ville de Tourcoing : +Par exemple, pour lister tous les bouchers de la ville de Tourcoing : ```{r, eval = FALSE} bouchers_tourcoing <- @@ -180,49 +124,38 @@ bouchers_tourcoing <- ) ``` -### Le _package_ [inseeLocalData](https://github.com/InseeFrLab/inseeLocalData) - -Ce _package_ permet de télécharger les données localisées à la commune, -diffusées sur dans la rubrique *Chiffres détaillés*, -sous forme de cubes prédéfinis. Cette API est hébergée sur le catalogue des -API de l'Insee. Une authentification par un jeton est donc nécessaire. - -Le _package_ comporte une fonction unique qui permet d’importer les données -présentes dans l’API *Données Locales* dans une liste contenant 4 objets : +### Le _package_ [melodi](https://inseefrlab.github.io/melodi/) -* les données statistiques ; -* les modalités de chaque variable ; -* l’information sur la zone demandée ; -* l’information sur la source et le jeu de données demandé. +Ce _package_ facilite l'utilisation des données et métadonnées diffusées par l'Insee +sur [le catalogue de données de l'Insee (melodi)](https://catalogue-donnees.insee.fr). +Il permet de lister, filtrer, télécharger et accéder aux métadonnées de l'ensemble des jeux de données visibles sur le catalogue, +en cours d'enrichissement. +Il s'appuie sur l'API melodi, accessible librement et donc sans besoin de configurer de jeton d'accès. -Exemple d'utilisation du _package_ pour importer le nombre -d'entreprises et d'établissements en 2017 (en géographie au 01/01/2017) -selon l'activité en 5 catégories et une indicatrice indiquant s'il s'agit -d'une entreprise individuelle ou non pour la commune de Nantes : - +Une fois installé, pour lister les jeux de données proposés par l'Insee : ```{r, eval = FALSE} -library(inseeLocalData) - -croisement <- "NA5_B-ENTR_INDIVIDUELLE" -jeu_donnees <- "GEO2017REE2017" -nivgeo <- "COM" -codgeo <- "44109" #CODE GEO DE NANTES -modalite <- "all.all" - -donneesAPI <- get_dataset(jeton, jeu_donnees, croisement, modalite, nivgeo, codgeo) +library(melodi) -donnees <- donneesAPI$donnees # pour accéder aux données -liste_code <- donneesAPI$liste_code # pour accéder aux nomenclatures -info_zone <- donneesAPI$info_zone # pour accéder aux données géographiques -source <- donneesAPI$source # pour accéder à la source +get_catalog() +``` +Pour récupérer toutes les données d'un jeu de données par son identifiant : +```{r, eval = FALSE} +data <- get_all_data("DS_POPULATIONS_REFERENCE") ``` - +Pour filtrer un jeu de données par critère géographiques, par exemple pour obtenir toutes les communes d'un EPCI : +```{r, eval = FALSE} +my_local_data_by_com <- get_local_data_by_com( + ds_name = "DS_POPULATIONS_REFERENCE", + geo = "244400404", # Nantes Métropole + geo_object = "EPCI" +) +``` -### Le _package_ [insee](https://github.com/InseeFr/R-Insee-Data/) +### Le _package_ [insee](https://github.com/pyr-opendatafr/R-Insee-Data) Ce _package_ permet de télécharger les données et leurs métadonnées diffusées sur le service `SDMX` de la Base de données Macroéconomique @@ -245,9 +178,6 @@ df %>% ``` - - - ```{r, eval = FALSE} library(insee) @@ -260,6 +190,12 @@ Il est possible de rajouter des filtres à ces fonctions afin de limiter le nombre de données importées (filtre sur la période, sur la date de mise à jour, sur les filtres). + + +### Le _package_ [eurostat](https://ropengov.github.io/eurostat/) + +Ce _package_ permet de télécharger les données mises à disposition par Eurostat. + ### Le _package_ [OECD](https://cran.r-project.org/web/packages/OECD/index.html) @@ -294,10 +230,10 @@ data <- get_dataset("DUR_D") ## Exemple d'utilisation d'une API sans _package_ Les exemples précédents proposaient l'accès à une API par le biais d'un _package_. -Pour lire les données d'une API ne possédant pas de _package_, il faut utiliser les deux _packages_ `R` suivants : +Pour lire les données d'une API ne possédant pas de _package_, il faut utiliser le _package_ `httr2` pour lancer la requête et traiter son retour; -- le _package_ `httr` pour lancer la requête ; -- puis le _package_ `jsonlite` pour transformer en `data.frame` le résultat de la requête (qui est structurée en `JSON`). +Au besoin pour des structures JSON complexes, le _package_ `jsonlite` peut être utilisé en complément pour transformer en `data.frame` +le résultat de la requête (qui est structurée en `JSON`). ::: {.callout-note} @@ -312,7 +248,12 @@ l'accès à des données par ce biais en `Python`. ::: -### Le _package_ `httr` + +### Le _package_ `httr2` (recommandé) + +A compléter + +### Le _package_ `httr` (déprécié) Le _package_ `httr` permet de se connecter aux sites web et de se connecter aux API. @@ -321,8 +262,8 @@ modifier les variables système : - `set_config()` permet de configurer l'accès internet utilisée par les fonctions du _package_. - `use_proxy()` permet de déterminer le proxy à utiliser. -De nombreuses institutions utilisent passent par un intermédiaire, le proxy, -pour accéder à internet. L'adresse du proxy est à ajouter au requête car sinon +De nombreuses institutions passent par un intermédiaire, le proxy, +pour accéder à internet. L'adresse du proxy est à ajouter aux requêtes car sinon `R` ne sait pas communiquer avec internet. Il s'agit d'un paramètre à ajouter dans les options `httr`.