From 4c68faa479a9e0a7e03474e960f8cb96c9cfc468 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?C=C3=A9dric=20Bobinec?= Date: Fri, 20 Feb 2026 17:15:20 +0100 Subject: [PATCH 1/9] balayage reco --- 03_Fiches_thematiques/Fiche_api.qmd | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/03_Fiches_thematiques/Fiche_api.qmd b/03_Fiches_thematiques/Fiche_api.qmd index f5312e3e..1952e342 100644 --- a/03_Fiches_thematiques/Fiche_api.qmd +++ b/03_Fiches_thematiques/Fiche_api.qmd @@ -6,10 +6,11 @@ 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 complexe le _package_ `jsonlite` peut être utilisé - 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. +il est recommandé d'utiliser l'un des _packages_ suivants : `doremifasol`, `melodi` (Melodi), `insee` (séries BDM). - 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`. From 4169988e0e2eb5b14ad4eb6a1b50353a8ff5ee34 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?C=C3=A9dric=20Bobinec?= Date: Fri, 20 Feb 2026 17:47:32 +0100 Subject: [PATCH 2/9] =?UTF-8?q?premi=C3=A8res=20relectures=20packages?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 03_Fiches_thematiques/Fiche_api.qmd | 157 ++++++++-------------------- 1 file changed, 46 insertions(+), 111 deletions(-) diff --git a/03_Fiches_thematiques/Fiche_api.qmd b/03_Fiches_thematiques/Fiche_api.qmd index 1952e342..837e157e 100644 --- a/03_Fiches_thematiques/Fiche_api.qmd +++ b/03_Fiches_thematiques/Fiche_api.qmd @@ -8,9 +8,9 @@ L'utilisateur souhaite accéder à des données _via_ une API. - 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_ `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 complexe le _package_ `jsonlite` peut être utilisé +- `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 utilisé - Pour accéder à des données disponibles sur le site , -il est recommandé d'utiliser l'un des _packages_ suivants : `doremifasol`, `melodi` (Melodi), `insee` (séries BDM). +il est recommandé d'utiliser l'un des _packages_ suivants : `doremifasol`, `melodi` (catalogue de données Melodi), `insee` (séries BDM). - 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`. @@ -50,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 @@ -73,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. @@ -94,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 : +### Le _package_ [doremifasol](https://inseefrlab.github.io/DoReMIFaSol) -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_ permet d'importer facilement dans R des données mises à disposition par différents canaux sur le site de l'Insee. -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. +Il permet entre autres de solliciter l'API Sirène dans une procédure de requêtage intégrée. -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 : +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} -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 : - -```{r, eval = FALSE} -usethis::edit_git_ignore(".Renviron") +INSEE_API_TOKEN='xxxxxxxx' ``` -::: -Enfin, pour créer le token temporaire, il suffit d'exécuter : +Il reste ensuite à préciser le type d'information souhaitée (unités légales, établissements...) et la requête via l'argument `argsApi`. - -```{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)) -``` - -Dès lors, vous pouvez accéder aux API de -l’Insee auxquelles votre application a souscrit. - - -### 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 <- @@ -181,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_ [melodi](https://inseefrlab.github.io/melodi/) -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 : +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. -* 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é. - - -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 : +Il s'appuie sur l'API melodi, accessible librement et donc sans besoin de configurer de jeton d'accès. +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" +library(melodi) -donneesAPI <- get_dataset(jeton, jeu_donnees, croisement, modalite, nivgeo, codgeo) - -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 @@ -246,9 +178,6 @@ df %>% ``` - - - ```{r, eval = FALSE} library(insee) @@ -261,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) From b7338141a041e053466cd6db842862e233e55d7a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?C=C3=A9dric=20Bobinec?= Date: Fri, 20 Feb 2026 17:55:15 +0100 Subject: [PATCH 3/9] a finir : httr2 --- 03_Fiches_thematiques/Fiche_api.qmd | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/03_Fiches_thematiques/Fiche_api.qmd b/03_Fiches_thematiques/Fiche_api.qmd index 837e157e..ec2f71e4 100644 --- a/03_Fiches_thematiques/Fiche_api.qmd +++ b/03_Fiches_thematiques/Fiche_api.qmd @@ -8,10 +8,10 @@ L'utilisateur souhaite accéder à des données _via_ une API. - 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_ `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 utilisé +- `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`, `melodi` (catalogue de données Melodi), `insee` (séries BDM). -- 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 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`. ::: @@ -230,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} @@ -248,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. @@ -257,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`. From 0ae1321bf8951b5af3d679c5025baa106c07bd09 Mon Sep 17 00:00:00 2001 From: cgoudeau Date: Tue, 3 Mar 2026 15:45:48 +0100 Subject: [PATCH 4/9] Update Fiche_api.qmd maj httr2 --- 03_Fiches_thematiques/Fiche_api.qmd | 81 +++++++++++++++++++++++++++-- 1 file changed, 77 insertions(+), 4 deletions(-) diff --git a/03_Fiches_thematiques/Fiche_api.qmd b/03_Fiches_thematiques/Fiche_api.qmd index ec2f71e4..3a3bd966 100644 --- a/03_Fiches_thematiques/Fiche_api.qmd +++ b/03_Fiches_thematiques/Fiche_api.qmd @@ -251,7 +251,69 @@ l'accès à des données par ce biais en `Python`. ### Le _package_ `httr2` (recommandé) -A compléter +Le _package_ `httr2` permet de se connecter aux sites web et aux API. Il offre des fonctionnalités modernes comme le gestion des échecs et l'extraction directe des réponses JSON. + + +### Accès à une API sans jeton + +Un appel à une API via `httr2` peut s'effectuer de la manière suivante : + +```{r, eval = FALSE} +resultats <- httr2::request(url) |> # url à interroger + httr2::req_perform() |> # effectuer la requête + httr2::resp_body_json(simplifyVector = FALSE) # extraire le corps de la réponse +``` +Prenons par exemple l'API d'*OpenFood Facts*, une base de données alimentaire. +Imaginons qu'on désire récupérer l'information sur un produit. Cela s'obtient +de la manière suivante : + +```{r} +url <- "https://world.openfoodfacts.org/api/v0/product/3017620425400.json" + +resultats <- httr2::request(url) |> # url à interroger + httr2::req_retry(max_tries = 3) |> # réessayer automatiquement en cas d'échec + httr2::req_timeout(30) |> # définir une limite de temps + httr2::req_perform() |> # effectuer la requête + httr2::resp_body_json(simplifyVector = FALSE) # extraire le corps de la réponse +``` +Le résultat JSON est formaté sous forme de liste imbriquée. + +```{r} +resultats +``` +Pour en faire une information exploitable, il est nécessaire de retraiter le résultat de la requête. +Par exemple en extrayant manuellement le libellé et le nutriscore d'un produit, ainsi que son indice de transformation NOVA : + +```{r} +dataset <- tibble::tibble( + product_name = resultats$product$product_name, + nova_groups = resultats$product$nova_groups, + nutriscore_grade = resultats$product$nutriscore_grade +) +``` +### Accès à une API avec jeton + +Pour les API protégées par des jetons, il faut rajouter +un paramètre d'identification. Les jetons d'authentification (*token*) +étant des informations personnelles, il ne faut pas les faire figurer dans +un script. Comme expliqué précédemment, ils peuvent être stockés +sous forme de variable d'environnement, par exemple +sous le nom `MON_JETON_SECRET`. Il suffit alors d'utiliser +`Sys.getenv` pour récupérer la valeur derrière le nom `MON_JETON_SECRET`, puis d'ajouter le jeton dans l'en-tête HTTP : + +```{r, eval = FALSE} +jeton <- Sys.getenv("MON_JETON_SECRET") # création d'une variable contenant le jeton + +library(httr2) + +resultats <- request(url) |> + req_headers(Authorization = paste("Bearer", jeton)) |> # ajout du jeton + req_retry(max_tries = 3) |> # retry automatique + req_timeout(30) |> # timeout + req_perform() |> # exécution de la requête + resp_body_json(simplifyVector = FALSE) # extraction JSON +``` + ### Le _package_ `httr` (déprécié) @@ -282,7 +344,7 @@ Le _package_ `httr` permet, lorsqu'on effectue une requête `GET` (une requête d'accès au résultat d'une recherche), de récupérer le résultat sous la forme d'un texte à retravailler. -### Accès à une API sans jeton +### Accès à une API sans jeton (httr, déprécié) En général, un appel à une API via `httr` s'effectue ainsi de la manière suivante : @@ -332,7 +394,7 @@ df ``` -### Accès à une API avec jeton +### Accès à une API avec jeton (httr, déprécié) Pour les API protégées par des jetons, il faut rajouter un paramètre d'identification. Les jetons d'authentification (*token*) @@ -358,8 +420,19 @@ res <- httr::content(httr::GET(url), ### Le _package_ `jsonlite` Ce _package_ propose principalement la fonction `fromJSON` qui permet de convertir une résultat en format `json` en un objet `R`. + + +```{r, eval = FALSE} +library(httr2) +library(jsonlite) +resp_text <- httr2::request(url) |> + httr2::req_perform() |> + httr2::resp_body_string() + +resultats <- fromJSON(resp_text, flatten = TRUE) +``` -### Temporisation +### Temporisation (revoir également : httr+jsonlite, et pas d'utilisation de Sys.sleep ?) Pour l'utilisation d'API avec un jeton, comme celle proposées sur le catalogue des API de l'Insee, le nombre de requête par minute est limité From 945c0696d19902a4f402fc3145db2f746b8afd73 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?C=C3=A9dric=20Bobinec?= Date: Wed, 11 Mar 2026 14:23:12 +0100 Subject: [PATCH 5/9] a poursuivre --- 03_Fiches_thematiques/Fiche_api.qmd | 59 ++++++++++++++++------------- 1 file changed, 33 insertions(+), 26 deletions(-) diff --git a/03_Fiches_thematiques/Fiche_api.qmd b/03_Fiches_thematiques/Fiche_api.qmd index 3a3bd966..93cc9c0f 100644 --- a/03_Fiches_thematiques/Fiche_api.qmd +++ b/03_Fiches_thematiques/Fiche_api.qmd @@ -11,8 +11,7 @@ le _package_ `httr2` pour transmettre des requêtes à l'API, [le package httr e - `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`, `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`. +- 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é. ::: @@ -128,10 +127,9 @@ bouchers_tourcoing <- 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 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. -Il s'appuie sur l'API melodi, accessible librement et donc sans besoin de configurer de jeton d'accès. +Le package s'appuie sur l'API melodi, accessible librement et donc sans besoin de configurer de jeton d'accès. Une fois installé, pour lister les jeux de données proposés par l'Insee : ```{r, eval = FALSE} @@ -145,7 +143,7 @@ Pour récupérer toutes les données d'un jeu de données par son identifiant : 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 : +Pour filtrer un jeu de données par critère géographiques, par exemple pour obtenir les données de toutes les communes d'un EPCI : ```{r, eval = FALSE} my_local_data_by_com <- get_local_data_by_com( @@ -200,9 +198,9 @@ Ce _package_ permet de télécharger les données mises à disposition par Euros ### Le _package_ [OECD](https://cran.r-project.org/web/packages/OECD/index.html) - Ce _package_ permet de télécharger les données mises à disposition sur le -site de l'[OCDE](https://stats.oecd.org/index.aspx?lang=fr). Cette API étant ouverte, son accès ne demande pas d'identification, ni de jeton. Il est uniquement nécessaire de déterminer les données souhaitées. +site de l'[OCDE](https://stats.oecd.org/index.aspx?lang=fr). +Cette API étant ouverte, son accès ne demande pas d'identification, ni de jeton. Il est uniquement nécessaire de déterminer les données souhaitées. ::: {.callout-warning} ## Spécificité Insee @@ -259,10 +257,13 @@ Le _package_ `httr2` permet de se connecter aux sites web et aux API. Il offre d Un appel à une API via `httr2` peut s'effectuer de la manière suivante : ```{r, eval = FALSE} -resultats <- httr2::request(url) |> # url à interroger - httr2::req_perform() |> # effectuer la requête - httr2::resp_body_json(simplifyVector = FALSE) # extraire le corps de la réponse +resultats <- httr2::request(url) |> # url à interroger + httr2::req_retry(max_tries = 3) |> # réessayer automatiquement en cas d'échec + httr2::req_timeout(30) |> # définir une limite de temps de réponse en secondes + httr2::req_perform() |> # effectuer la requête + httr2::resp_body_json(simplifyVector = TRUE) # extraire le corps de la réponse ``` + Prenons par exemple l'API d'*OpenFood Facts*, une base de données alimentaire. Imaginons qu'on désire récupérer l'information sur un produit. Cela s'obtient de la manière suivante : @@ -274,15 +275,16 @@ resultats <- httr2::request(url) |> # url à interroger httr2::req_retry(max_tries = 3) |> # réessayer automatiquement en cas d'échec httr2::req_timeout(30) |> # définir une limite de temps httr2::req_perform() |> # effectuer la requête - httr2::resp_body_json(simplifyVector = FALSE) # extraire le corps de la réponse + httr2::resp_body_json(simplifyVector = TRUE) # extraire le corps de la réponse ``` -Le résultat JSON est formaté sous forme de liste imbriquée. +Le résultat JSON est formaté sous forme de liste imbriquée : ```{r} -resultats +str(resultats, max.level = 1) ``` + Pour en faire une information exploitable, il est nécessaire de retraiter le résultat de la requête. -Par exemple en extrayant manuellement le libellé et le nutriscore d'un produit, ainsi que son indice de transformation NOVA : +Par exemple, en extrayant ainsi manuellement les variables d'intérêt dans la liste (libellé, indice de transformation NOVA, nutriscore) : ```{r} dataset <- tibble::tibble( @@ -290,7 +292,10 @@ dataset <- tibble::tibble( nova_groups = resultats$product$nova_groups, nutriscore_grade = resultats$product$nutriscore_grade ) + +dataset ``` + ### Accès à une API avec jeton Pour les API protégées par des jetons, il faut rajouter @@ -307,15 +312,14 @@ jeton <- Sys.getenv("MON_JETON_SECRET") # création d'une variable contenant le library(httr2) resultats <- request(url) |> - req_headers(Authorization = paste("Bearer", jeton)) |> # ajout du jeton - req_retry(max_tries = 3) |> # retry automatique - req_timeout(30) |> # timeout - req_perform() |> # exécution de la requête - resp_body_json(simplifyVector = FALSE) # extraction JSON + req_headers(Authorization = paste("Bearer", jeton)) |> # ajout du jeton + req_retry(max_tries = 3) |> # retry automatique + req_timeout(30) |> # timeout + req_perform() |> # exécution de la requête + resp_body_json(simplifyVector = TRUE) # extraction JSON ``` - -### Le _package_ `httr` (déprécié) +### Le _package_ `httr` (déprécié, privilégier `httr2`) Le _package_ `httr` permet de se connecter aux sites web et de se connecter aux API. @@ -419,15 +423,18 @@ res <- httr::content(httr::GET(url), ### Le _package_ `jsonlite` -Ce _package_ propose principalement la fonction `fromJSON` qui permet de convertir une résultat en format `json` en un objet `R`. - +Ce _package_ propose principalement la fonction `fromJSON` qui permet de convertir une résultat en format `json` en un objet `R`. +Son usage était nécess +Son usage peut être nécessaire pour traiter des structures JSON complexes, `httr2::resp_body_json()` + + ```{r, eval = FALSE} library(httr2) library(jsonlite) resp_text <- httr2::request(url) |> httr2::req_perform() |> - httr2::resp_body_string() + httr2::resp_body_string() resultats <- fromJSON(resp_text, flatten = TRUE) ``` @@ -443,7 +450,7 @@ La fonction permettant cela est `Sys.sleep`. Par exemple, pour laisser 30 secondes d'attente, taper `Sys.sleep(30)`. -**Exemple d'utilisation sur l'API interne RMèS** +### Exemple d'utilisation sur l'API interne RMèS Une API interne sur les métadonnées de l'Insee est disponible (programme `RMès`). Elle permet d'obtenir de manière simplifiée des métadonnées From 2948aee11f1837cd536c0eee2321d6cd1516203b Mon Sep 17 00:00:00 2001 From: ggj62i Date: Fri, 20 Mar 2026 16:29:52 +0000 Subject: [PATCH 6/9] =?UTF-8?q?relecture=20globale,=20r=C3=A9organisation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 03_Fiches_thematiques/Fiche_api.qmd | 255 ++++++++++++---------------- 1 file changed, 107 insertions(+), 148 deletions(-) diff --git a/03_Fiches_thematiques/Fiche_api.qmd b/03_Fiches_thematiques/Fiche_api.qmd index 93cc9c0f..11104525 100644 --- a/03_Fiches_thematiques/Fiche_api.qmd +++ b/03_Fiches_thematiques/Fiche_api.qmd @@ -7,10 +7,10 @@ L'utilisateur souhaite accéder à des données _via_ une API. - 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_ `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) +le _package_ `httr2` pour transmettre des requêtes à l'API, [qui remplace le package `httr` désormais *superseded*](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`, `melodi` (catalogue de données Melodi), `insee` (séries BDM). +- Pour accéder à des données de l'Insee, +il est recommandé d'utiliser l'un des _packages_ suivants : `doremifasol` (fichiers sur [insee.fr](https://www.insee.fr/), API sirene), `melodi` ([catalogue de données Melodi](https://catalogue-donnees.insee.fr)), `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é. ::: @@ -206,8 +206,8 @@ Cette API étant ouverte, son accès ne demande pas d'identification, ni de jeto ## Spécificité Insee Ce _package_ utilise la librairie `rsmdx` qui n'est pas compatible avec -la technologie *Direct Access*. Il ne fonctionne pas en télétravail pour les -postes nomades qui accèdent à internet par ce biais. En revanche il fonctionne sur site. +la technologie *Direct Access*. Il ne fonctionne pas sur poste en télétravail pour les +postes nomades Insee qui accèdent à internet par ce biais. En revanche il fonctionne sur site. ::: Voici quelques utilisations possibles de ce _package_ : @@ -225,13 +225,10 @@ browse_metadata("DUR_D") data <- get_dataset("DUR_D") ``` -## Exemple d'utilisation d'une API sans _package_ +## Utiliser 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 le _package_ `httr2` pour lancer la requête et traiter son retour; - -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`). +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 ::: {.callout-note} @@ -250,18 +247,19 @@ l'accès à des données par ce biais en `Python`. ### Le _package_ `httr2` (recommandé) Le _package_ `httr2` permet de se connecter aux sites web et aux API. Il offre des fonctionnalités modernes comme le gestion des échecs et l'extraction directe des réponses JSON. + ### Accès à une API sans jeton -Un appel à une API via `httr2` peut s'effectuer de la manière suivante : +Un appel à une API répondant au format JSON via `httr2` peut s'effectuer de la manière suivante : ```{r, eval = FALSE} -resultats <- httr2::request(url) |> # url à interroger - httr2::req_retry(max_tries = 3) |> # réessayer automatiquement en cas d'échec - httr2::req_timeout(30) |> # définir une limite de temps de réponse en secondes - httr2::req_perform() |> # effectuer la requête - httr2::resp_body_json(simplifyVector = TRUE) # extraire le corps de la réponse +resultats <- httr2::request(url) |> # url à interroger + httr2::req_retry(max_tries = 3) |> # réessayer automatiquement en cas d'échec + httr2::req_timeout(60) |> # définir une limite de temps en secondes plus haute si besoin + httr2::req_perform() |> # effectuer la requête + httr2::resp_body_json() # extraire le corps de la réponse ``` Prenons par exemple l'API d'*OpenFood Facts*, une base de données alimentaire. @@ -271,11 +269,11 @@ de la manière suivante : ```{r} url <- "https://world.openfoodfacts.org/api/v0/product/3017620425400.json" -resultats <- httr2::request(url) |> # url à interroger - httr2::req_retry(max_tries = 3) |> # réessayer automatiquement en cas d'échec - httr2::req_timeout(30) |> # définir une limite de temps - httr2::req_perform() |> # effectuer la requête - httr2::resp_body_json(simplifyVector = TRUE) # extraire le corps de la réponse +resultats <- httr2::request(url) |> # url à interroger + httr2::req_retry(max_tries = 3) |> # réessayer automatiquement en cas d'échec + httr2::req_timeout(60) |> # définir une limite de temps en secondes plus haute si besoin + httr2::req_perform() |> # effectuer la requête + httr2::resp_body_json() # extraire le corps de la réponse ``` Le résultat JSON est formaté sous forme de liste imbriquée : @@ -296,7 +294,7 @@ dataset <- tibble::tibble( dataset ``` -### Accès à une API avec jeton +#### Accès à une API avec jeton Pour les API protégées par des jetons, il faut rajouter un paramètre d'identification. Les jetons d'authentification (*token*) @@ -304,22 +302,99 @@ un paramètre d'identification. Les jetons d'authentification (*token*) un script. Comme expliqué précédemment, ils peuvent être stockés sous forme de variable d'environnement, par exemple sous le nom `MON_JETON_SECRET`. Il suffit alors d'utiliser -`Sys.getenv` pour récupérer la valeur derrière le nom `MON_JETON_SECRET`, puis d'ajouter le jeton dans l'en-tête HTTP : +`Sys.getenv` pour récupérer la valeur derrière le nom `MON_JETON_SECRET`, puis d'ajouter le jeton dans l'en-tête HTTP (nommée `X-INSEE-Api-Key-Integration` pour les API de l'Insee) ```{r, eval = FALSE} -jeton <- Sys.getenv("MON_JETON_SECRET") # création d'une variable contenant le jeton - library(httr2) +jeton <- Sys.getenv("MON_JETON_SECRET") # création d'une variable contenant le jeton + resultats <- request(url) |> - req_headers(Authorization = paste("Bearer", jeton)) |> # ajout du jeton + req_headers(`X-INSEE-Api-Key-Integration` = jeton) |> # ajout du jeton req_retry(max_tries = 3) |> # retry automatique - req_timeout(30) |> # timeout + req_timeout(60) |> # timeout req_perform() |> # exécution de la requête - resp_body_json(simplifyVector = TRUE) # extraction JSON + resp_body_json() # extraction JSON ``` -### Le _package_ `httr` (déprécié, privilégier `httr2`) + +#### Exemple d'utilisation de l'API Métadonnées Insee + +Une API sur les métadonnées de l'Insee est disponible [sur le portail des API de l'Insee](https://portail-api.insee.fr/catalog/api/5029cf12-e930-4d24-a9cf-12e9307d241d?aq=ALL). +Elle permet d'obtenir de manière simplifiée des métadonnées +(sources, concepts, liste de codes géographiques). + +Voici un exemple de requête pour obtenir des informations sur une catégorie juridique : + +```{r, eval = FALSE} +library(httr2) + +url <- "https://api.insee.fr/metadonnees/codes/cj/n2/10" + +resultats <- request(url) |> + req_perform() |> # exécution de la requête + resp_body_json() # extraction JSON +``` + +#### Exemple d'utilisation de l'API Sirene + +Cet exemple va aller chercher les liens de succession pour un établissement : + +```{r, eval = FALSE} +library(httr2) + +jeton <- Sys.getenv("MON_JETON_SECRET") # création d'une variable contenant le jeton + +url <- "https://api.insee.fr/api-sirene/3.11/siret/liensSuccession?q=siretEtablissementPredecesseur:39478192600016" + +resultats <- request(url) |> + req_headers(`X-INSEE-Api-Key-Integration` = jeton) |> # ajout du jeton + req_perform() |> # exécution de la requête + resp_body_json() # extraction JSON + +sortie <- as.data.frame(resultats$liensSuccession) +``` + +L'API Sirene permet d'effectuer des recherches multicritères. Dans ce cas, il +faut séparer les codes par `%20OR%20` (code HTML signifiant ` OR `) : + +```{r, eval = FALSE} +url <- "https://api.insee.fr/api-sirene/3.11/siret/liensSuccession?q=siretEtablissementPredecesseur%3A39478192600016%20OR%20siretEtablissementPredecesseur%3A39488939800027" + +resultats <- request(url) |> + req_headers(`X-INSEE-Api-Key-Integration` = jeton) |> # ajout du jeton + req_perform() |> # exécution de la requête + resp_body_json() # extraction JSON + +sortie <- as.data.frame(resultats$liensSuccession) +``` + +## Le _package_ `jsonlite` + +Ce _package_ propose principalement la fonction `fromJSON` qui permet de convertir une résultat en format `json` en un objet `R`. +Il était nécessaire en complément de `httr`, mais désormais `httr2` gère cette conversion nativement avec `resp_body_json()`. +Son usage peut être nécessaire pour traiter des structures JSON complexes pour laquelle le traitement par `httr2` ne convient pas, dans ce cas retourner un résultat sous forme textuel, puis le traiter avec jsonlite : + +```{r, eval = FALSE} +library(httr2) +library(jsonlite) +resp_text <- httr2::request(url) |> + httr2::req_perform() |> + httr2::resp_body_string() + +resultats <- jsonlite::fromJSON(resp_text, flatten = TRUE) +``` + +## Limites de requêtes et temporisation + +Pour l'utilisation d'API comme celles proposées sur le catalogue des API de l'Insee, +le nombre de requête par minute est limité. +Pour ne pas être bloqué par cette limite, il peut être utile de temporiser +les appels successifs en introduisant une latence. +La fonction permettant cela est `Sys.sleep`. Par exemple, pour +laisser 30 secondes d'attente, ajouter `Sys.sleep(30)`. + +## (déprécié, privilégier désormais `httr2`) Le _package_ `httr` Le _package_ `httr` permet de se connecter aux sites web et de se connecter aux API. @@ -348,7 +423,7 @@ Le _package_ `httr` permet, lorsqu'on effectue une requête `GET` (une requête d'accès au résultat d'une recherche), de récupérer le résultat sous la forme d'un texte à retravailler. -### Accès à une API sans jeton (httr, déprécié) +### Accès à une API sans jeton avec `httr` En général, un appel à une API via `httr` s'effectue ainsi de la manière suivante : @@ -379,13 +454,7 @@ resultats <- ``` Le résultat est formaté sous forme de JSON, ce qui est pratique mais peu -intelligible : - -```{r} -jsonlite::prettify(resultats) -``` - -Pour en faire une information exploitable, il est nécessaire de retraiter le résultat de la requête. Par exemple, pour n'extraire que le libellé et le nutriscore d'un produit, ainsi que son indice de transformation NOVA, il faut utiliser une boucle sur les différentes caractéristiques à extraire : +intelligible. Pour en faire une information exploitable, il est nécessaire de retraiter le résultat de la requête. Par exemple, pour n'extraire que le libellé et le nutriscore d'un produit, ainsi que son indice de transformation NOVA, il faut utiliser une boucle sur les différentes caractéristiques à extraire : ```{r} df <- data.frame( @@ -398,7 +467,7 @@ df ``` -### Accès à une API avec jeton (httr, déprécié) +### Accès à une API avec jeton avec `httr` Pour les API protégées par des jetons, il faut rajouter un paramètre d'identification. Les jetons d'authentification (*token*) @@ -421,116 +490,6 @@ res <- httr::content(httr::GET(url), encoding='UTF-8') ``` -### Le _package_ `jsonlite` - -Ce _package_ propose principalement la fonction `fromJSON` qui permet de convertir une résultat en format `json` en un objet `R`. -Son usage était nécess -Son usage peut être nécessaire pour traiter des structures JSON complexes, `httr2::resp_body_json()` - - - -```{r, eval = FALSE} -library(httr2) -library(jsonlite) -resp_text <- httr2::request(url) |> - httr2::req_perform() |> - httr2::resp_body_string() - -resultats <- fromJSON(resp_text, flatten = TRUE) -``` - -### Temporisation (revoir également : httr+jsonlite, et pas d'utilisation de Sys.sleep ?) - -Pour l'utilisation d'API avec un jeton, comme celle proposées sur le -catalogue des API de l'Insee, le nombre de requête par minute est limité -(30 pour un compte standard sur le catalogue des API). -Pour ne pas être bloqué par cette limite, il est important de temporiser -les appels successifs en introduisant une latence. -La fonction permettant cela est `Sys.sleep`. Par exemple, pour -laisser 30 secondes d'attente, taper `Sys.sleep(30)`. - - -### Exemple d'utilisation sur l'API interne RMèS - -Une API interne sur les métadonnées de l'Insee est disponible (programme `RMès`). -Elle permet d'obtenir de manière simplifiée des métadonnées -(sources, concepts, liste de codes géographiques). -Comme cette API est disponible en interne à l'Insee, il n'y a pas, comme pour accéder -à celles sur internet, de proxy. - -Voici un exemple de requête pour accéder aux données au niveau -division de la `Naf-rev2` : - -```{r, eval = FALSE} -library(dplyr) -library(stringr) -library(httr) -library(jsonlite) - -# L'API est disponible en interne. Il n'y a pas de proxy pour cette API -set_config(use_proxy("")) - -# url de la requête : ici on souhaite afficher la naf rev 2 -url <- "url_de_la_requete" - - -# connexion à l'API pour récupérer les données en JSON -res <- content(GET(url), - as="text", content_type_json(), encoding='UTF-8') - -# transformation des données pour les transformer en dataframe -res_ok <- as.data.frame(fromJSON(res)) - -# travail de la table pour obtenir le niveau division de la NAF-rev2 -division <- res_ok %>% - filter(str_detect(uri,'division')) %>% - select(c('code', 'intituleFr')) -``` - -::: {.callout-warning} -## Spécificité Insee - -L'URL de cette API est uniquement disponible en interne à l'Insee. Elle n'est pas rendu publique pour des raisons de sécurité. -::: - - -### Exemple d'utilisation de l'[API Sirene](https://api.insee.fr/catalogue/site/themes/wso2/subthemes/insee/pages/item-info.jag?name=Sirene&version=V3&provider=insee) - -Cet exemple va aller chercher les liens de succession pour un établissement : - -```{r, eval = FALSE} -library(apinsee) -library(httr) -library(jsonlite) - -url <- "https://api.insee.fr/entreprises/sirene/V3/siret/liensSuccession?q=siretEtablissementPredecesseur:39478192600016" -url <- URLencode(url, reserved = TRUE) -token <- insee_auth() -set_config(config(token = token)) -res <- content(GET(url, config(token = token)), - as="text", - content_type_json(), - encoding='UTF-8') - -res <- fromJSON(res) -sortie <- as.data.frame(res$liensSuccession) -``` - -L'API Sirene permet d'effectuer des recherches multicritères. Dans ce cas, il -faut séparer les codes par `%20OR%20` (code HTML signifiant ` OR `) : - -```{r, eval = FALSE} -url <- "https://api.insee.fr/entreprises/sirene/V3/siret/liensSuccession?q=siretEtablissementPredecesseur%3A39478192600016%20OR%20siretEtablissementPredecesseur%3A39488939800027" -token <- apinsee::insee_auth() -set_config(config(token = token)) -res <- content(httr::GET(url, httr::config(token = token)), - as="text", - content_type_json(), - encoding='UTF-8') - -res<-fromJSON(res) -sortie <- as.data.frame(res$liensSuccession) -```