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 avec leur documentation.

Sur la page de la documentation de l'API, plusieurs éléments sont disponbiles.
La partie qui nous intéresse est la section datasets.
Cliquez sur la ligne de la requête GET /datasets/ (1) puis sur le bouton Try it out (2).

Nous filtrons la requête en renseignant l'ID de l'organisation Koumoul dans les paramètres.

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

Pour Koumoul, il s'agit de l'ID 589596c188ee3877169b81a4, que nous renseignons dans la section organisation de la documentation de l'API.

Cliquez sur le bouton Execute (4) qui se trouve plus bas dans la page et cliquez sur le bouton Download (5) pour obtenir le résultat de votre requête.

La requête envoyée est également disponible (encadré) :

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

Nous avons demandé d'envoyer 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 dans un éditeur de texte.

Sur le fichier JSON, nous constatons que la donnée est contenue dans la section data.

Pour créer un traitement, vous devez disposer d'un plan avec des quotas de traitement et être administrateur de votre organisation.

Sur la page des traitements, ajoutez un traitement à l'aide du bouton d'action sur votre droite.

Choisissez le nom du traitement, sélectionnez le type JSON et enregistrez-le.

Sur la page de configuration, vous pouvez :

1. Rendre le traitement actif ou inactif ;
2. Choisir la périodicité (mensuel, hebdomadaire ou horaire), ainsi que le jour et l'heure du traitement ;
3. Choisir l'action du traitement : créer un jeu de données / mettre à jour un jeu de données de type fichier ou de type incrémental ;
4. Renseigner les paramètres.

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

Dans la section des paramètres, vous pouvez renseigner l'adresse de l'API.
Pour notre exemple, nous utilisons l'adresse concernant Koumoul :

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

Lors de la découverte des données JSON de l'API data.gouv.fr, nous constatons que les données sont contenues dans l'élément data.

1. Renseignez la requête à réaliser ;
2. Renseignez l'élément contenant les données, ici, il s'agit de data ;
3. Ajoutez les différentes colonnes que vous souhaitez obtenir dans votre catalogue.

Pour ajouter un élément, il vous faudra :

1. Le chemin de la colonne dans le JSON,
2. Le nom de la colonne souhaité dans votre jeu de données,
3. Le type de la colonne.

Les différentes colonnes que vous pouvez ajouter sont présentes dans le fichier JSON.

Par exemple, nous pouvons ajouter les colonnes :

• title de type texte : correspond au titre de notre jeu de données publie sur data.gouv.fr,
• created_at de type texte,
• description de type texte,
• uri de type texte,
• id de type texte,
• uri de type texte,
• metrics.views de type texte.

Vous pouvez ajouter d'autres colonnes correspondant à des éléments présents dans le fichier JSON.

Exécutez le traitement pour créer votre jeu de données Catalogue data.gouv.fr.

Le jeu de données contient les colonnes que vous avez renseignées dans le traitement.
Chaque ligne 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.

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

Copiez la clé que vous venez de créer et copiez-la dans la section valeur des paramètres.

Exécutez à nouveau votre jeu de données.

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

Pour obtenir vos jeux de données, remplacez l'ID de l'organisation Koumoul dans l'URL de l'API 589596c188ee3877169b81a4 par la valeur de votre ID.

Si vous avez des remarques sur ce cours, n'hésitez pas à nous contacter pour nous en faire part.