Le traitement JSON permet d'importer des données JSON à partir d'une API pour, par exemple, les convertir au format CSV et les intégrer sur la plateforme Koumoul.

Dans ce tutoriel, nous verrons comment importer la liste des jeux de données publiés sur data.gouv.fr pour une organisation.

Le portail de données gouvernemental data.gouv.fr met à disposition des API.

Sur la page de la documentation de l'API, plusieurs éléments sont disponibles. La section qui nous intéresse est datasets.

Cliquez sur la ligne de la requête GET /datasets/ [1], puis sur le bouton Try it out out [2]. Le bouton Try it out permet de renseigner des valeurs dans les paramètres et d'exécuter une requête à l'API.

Nous allons exécuter une requête, mais avant cela, nous allons la configurer en renseignant l'ID de l'organisation Koumoul dans les paramètres.

Vous pouvez retrouver l'ID de votre organisation en vous connectant à votre compte data.gouv.fr et en cliquant sur votre organisation dans le menu.

Pour Koumoul, l'ID est 589596c188ee3877169b81a4 [2], que nous renseignons dans la section organisation de la documentation de l'API.

Cliquez sur le bouton Execute [4] situé plus bas dans la page, puis sur le bouton Download [5] pour obtenir le résultat de votre requête.

La requête envoyée est également visible (encadrée sur l'image précédente) :

https://www.data.gouv.fr/api/1/datasets/?page=1&page_size=20&organization=589596c188ee3877169b81a4

Nous avons demandé la première page contenant vingt jeux de données pour l'organisation avec l'ID 589596c188ee3877169b81a4 (Koumoul).

Nous pouvons voir le résultat de cette demande en ouvrant le fichier JSON, que nous avons téléchargé [5], dans un éditeur de texte.

Dans le fichier JSON, nous constatons que les données sont contenues dans la section data.

Pour créer un traitement, il est nécessaire de disposer d'un plan incluant des quotas de traitement et d'être administrateur de votre organisation.

Sur la page des traitements, utilisez le bouton d'action pour ajouter un traitement.

Renseignez le nom du traitement, choisissez le type Import d'API JSON, puis enregistrez-le.

Sur la page de configuration, vous avez la possibilité de :

1. Activer ou désactiver le traitement ;
2. Sélectionner l'action du traitement : créer un jeu de données ou mettre à jour un jeu de données de type fichier ou incrémental ;
3. Titre du JDD sur Data Fair ;
4. Définir la périodicité (mensuelle, hebdomadaire ou horaire), ainsi que le jour et l'heure d'exécution du traitement ;
5. Spécifiez l'adresse source de l'API ;
6. Champs de l'API à récuperer.

Comme vous pouvez le constater sur l'image, nous avons choisi de déclencher le traitement manuellement (aucune plannification) pour importer les jeux de données publiés par l'organisation Koumoul sur data.gouv.fr.

Dans la section Source de données, vous pouvez renseigner l'adresse de l'API. Pour notre exemple, nous utilisons l'adresse suivante pour Koumoul :

https://www.data.gouv.fr/api/1/datasets/?page=1&page_size=20&organization=589596c188ee3877169b81a4

Nous allons ensuite completer l'onglet Champs à récuperer.

Nous avons constaté que les données du fichier JSON se trouvent dans la section data [1].

Nous allons ensuite ajouter un élément du fichier JSON [2] à notre jeu de données.

Recherchez dans le fichier JSON les éléments qui vous intéressent. Dans notre image, nous avons ajouté deux éléments, title et created_at, du JSON qui auront respectivement les noms de colonnes titre et date de création [3] dans notre jeu de données.

Nous pouvons ajouter d'autres éléments du fichier JSON tels que :

• description : description du jeu de données,
• uri : adresse du jeu de données,
• id : idenfiant data.gouv.fr du jeu de données,
• metrics.views : nombre de vues de la page sur data.gouv.fr

Exécutez le traitement pour créer votre jeu de données intitulé Jeux de données Koumoul sur Data.gouv.fr.

Le jeu de données inclut les colonnes que vous avez spécifiées dans le traitement. Chaque ligne de votre jeu de données dans Data Fair correspond à un jeu de données publié sur data.gouv.fr.

Si vous souhaitez accéder à des données privées, le traitement JSON vous permet d'utiliser différentes méthodes d'authentification.

Pour nous connecter à data.gouv.fr, nous allons utiliser la méthode par clé d'API, API key, dans l'onglet Source de données.

Vous pouvez créer votre clé d'API sur la page du profil de votre compte data.gouv.fr.

Copiez la clé que vous venez de créer et collez-la dans la section Clé.

Relancez le traitement de votre jeu de données.

Le traitement de données ajoutera à nouveau les jeux de données publics de votre catalogue, ainsi que les jeux de données privés.

Si vous souhaitez obtenir les jeux de données de votre organisation, remplacez l'ID de l'organisation Koumoul dans l'URL de l'API, 589596c188ee3877169b81a4, par votre propre ID :
https://www.data.gouv.fr/api/1/datasets/?page=1&page_size=20&organization=589596c188ee3877169b81a4

Vous pouvez également modifier la taille des pages avec &page_size=20 ou utiliser la pagination si vous avez plus de 20 jeux de données publiés sur data.gouv.fr.

Si vous avez des remarques sur ce cours, n'hésitez pas à nous les communiquer.