Pour convertir un JSON imbriqué en CSV, utilisez un convertisseur JSON vers CSV en ligne qui vous permet de choisir quel tableau JSON deviendra les lignes du CSV. Ce choix est bien plus important qu’il n’y paraît. Les exports JSON réels commencent souvent par des métadonnées, des informations de pagination ou des objets enveloppes, tandis que les données utiles se trouvent dans un chemin comme results, data.items ou payload.records.
J’aborde généralement la conversion JSON vers CSV à travers trois décisions :
- Quel tableau doit devenir les lignes ?
- Quels champs d’objets imbriqués doivent devenir des colonnes ?
- Quels tableaux faut-il concaténer, conserver au format JSON ou développer en lignes distinctes ?
Une fois ces questions réglées, vous retrouvez un workflow CSV classique : prévisualiser le résultat, vérifier les colonnes, puis télécharger un fichier CSV compatible avec un tableur, un CRM, un outil de BI ou un processus de nettoyage de données.
📌 En bref
Commencez par définir ce que doit représenter une ligne du CSV. Dans cet exemple, je veux une entreprise par ligne : le nœud de lignes sera donc
$.results. Je peux ensuite aplatir les métriques de l’entreprise et décider comment traiter des tableaux commecontactsettags.
Dans ce guide, j’utiliserai un export JSON imbriqué contenant 20 000 entreprises sous results. Le même workflow convient aux réponses d’API, aux résultats de scraping, aux logs de webhooks, aux exports CRM et aux données de marketplaces lorsque les enregistrements utiles ne se trouvent pas à la racine du JSON.
Accès rapide :
- Exemple de fichier JSON imbriqué
- Convertir un JSON imbriqué en CSV avec Datablist
- Choisir le bon nœud de lignes
- Aplatir les objets JSON imbriqués
- Gérer les tableaux dans les lignes JSON
- Vérifier et télécharger le CSV
Exemple de fichier JSON imbriqué
Pour cet exemple, imaginez un export JSON volumineux provenant d’une API ou d’un outil de scraping. Le fichier pèse environ 8,8 Mo et contient 20 000 enregistrements dans un tableau results de premier niveau.
L’objet racine se présente ainsi :
{
"meta": {
"generatedAt": "2026-07-04T10:00:00Z",
"source": "stress_test"
},
"results": [
{
"id": 0,
"name": "NbDXeG4Gyg",
"website": "https://example-0.com",
"contacts": [
{
"name": "Ava Martin",
"emails": [
"ava@example-0.com"
],
"phones": [
"+1 555 0100"
]
},
{
"name": "Noah Lee",
"emails": [
"noah@example-0.com"
],
"phones": []
}
],
"tags": "enterprise",
"metrics": {
"employees": 124,
"revenue": {
"amount": 476171,
"currency": "USD"
}
},
"createdAt": "2026-06-25T09:12:00Z"
},
{
"id": 1,
"name": "DwwGmkzmBi",
"website": "https://example-1.com",
"contacts": [
{
"name": "Mia Chen",
"emails": [
"mia@example-1.com"
],
"phones": [
"+1 555 0101"
]
}
],
"tags": [
"saas",
"mid-market"
],
"metrics": {
"employees": 47,
"revenue": null
},
"createdAt": "2026-06-26T14:33:00Z"
}
]
}C’est typiquement le genre de fichier qui met les convertisseurs basiques en difficulté. Les enregistrements ne correspondent pas à l’objet racine : ils se trouvent dans results. Ils contiennent également des objets et tableaux imbriqués, des valeurs mêlant chaînes de caractères et tableaux, des valeurs nulles et des dates.
🔍 Pourquoi ce fichier constitue un bon test
Un simple tableau JSON plat ne teste que le cas le plus facile. Ce fichier couvre les choix qui comptent vraiment dans les exports réels : métadonnées d’enveloppe, tableau d’enregistrements imbriqué, champs objets, champs tableaux, valeurs mixtes et valeurs nulles.
Voici la structure des premières lignes :
| Ligne | Format de Website | Nombre de contacts | Format de Tags | Chiffre d’affaires |
|---|---|---|---|---|
| 0 | Chaîne | 2 | Chaîne | Montant et devise |
| 1 | Chaîne | 2 | Tableau | Null |
| 2 | Tableau | 1 | Tableau | Null |
Le CSV cible doit contenir une entreprise par ligne. Je veux transformer en colonnes les champs utiles tels que id, name, website, employees, amount, currency et createdAt. Pour des champs comme contacts et tags, je dois choisir quelle part de leur structure conserver.
Convertir un JSON imbriqué en CSV avec Datablist
Ouvrez le convertisseur JSON de Datablist. Vous pouvez coller votre JSON dans l’éditeur ou importer un fichier .json.
Pour une petite réponse d’API, le copier-coller convient très bien. Pour un export plus volumineux, je préfère importer le fichier afin d’éviter toute troncature accidentelle. Son contenu est lu dans le navigateur et la conversion s’effectue localement, sans envoi aux serveurs de Datablist.
Une fois le JSON chargé, Datablist analyse sa structure et recherche les tableaux d’objets. L’outil accepte aussi bien les tableaux que les objets à la racine, puis inspecte des chemins imbriqués comme $.results, $.data.items ou des tableaux encore plus profonds.
Lorsque le fichier est difficile à comprendre, il m’arrive de l’ouvrir d’abord dans JSONCrack. Son arborescence visuelle aide à repérer le tableau qui doit devenir les lignes. Cette étape reste facultative, mais elle est utile si le fichier contient plusieurs tableaux candidats.
Dans cet exemple, le bon nœud de lignes est :
$.results
Je choisis $.results parce que je veux une entreprise par ligne. Chaque élément de ce tableau devient une ligne du CSV.
Datablist peut recommander un nœud de lignes, mais je le vérifie toujours manuellement. C’est à cette étape que surviennent la plupart des erreurs de conversion. Un fichier JSON peut contenir un tableau parent d’entreprises, un tableau enfant de contacts et un autre tableau enfant de tags ou d’événements. Ce sont tous des tableaux, mais un seul correspond au CSV recherché.
⚠️ Changer de nœud de lignes modifie le jeu de données
$.resultset$.results[].contactssont tous deux des nœuds valides, mais ils ne produisent pas le même CSV. Choisissez le tableau parent pour obtenir des lignes de comptes. Choisissez le tableau enfant si les éléments imbriqués constituent votre jeu de données.
Pour cet article, je conserve le nœud parent :
$.resultsproduit une entreprise ou un compte par ligne.$.results[].contactsproduit un contact par ligne.
Cette seconde option peut être la bonne, mais elle change le résultat. Un CSV au niveau des contacts convient pour créer une liste de personnes. Un CSV au niveau des entreprises est préférable pour nettoyer des comptes, enrichir des entreprises, importer des enregistrements dans un CRM ou analyser des métriques.
Choisir le bon nœud de lignes
Un nœud de lignes est le tableau JSON dont les éléments deviennent les lignes du CSV.
Voici les exemples les plus courants :
| Chemin JSON | À privilégier lorsque |
|---|---|
$.results | Les enregistrements se trouvent sous une clé results |
$.data.items | Une API regroupe les enregistrements dans un objet data |
$.payload.records | Un webhook ou un export interne place les enregistrements sous payload |
$.results[].contacts | Vous voulez un contact imbriqué par ligne |
Avant de choisir, je me pose toujours une question : que doit représenter une ligne ?
Si une ligne doit représenter une entreprise, un compte, une commande, un produit, une annonce ou un événement, choisissez le tableau parent. Si elle doit représenter un contact, une adresse e-mail, une ligne de commande, un prix, un commentaire ou un événement enfant, choisissez le tableau enfant.
Cela paraît simple, mais ce choix transforme l’ensemble du CSV.
Avec $.results, le CSV conserve le contexte de l’entreprise. Le champ contacts reste une valeur imbriquée dans la ligne de l’entreprise, sauf si vous décidez de traiter les contacts séparément. Avec $.results[].contacts, le CSV devient une liste de contacts, mais les champs de l’entreprise parente ne sont pas ajoutés automatiquement, sauf si le convertisseur intègre cette fonction dans une version future.
Par défaut, je commence par le tableau parent. C’est un premier export plus sûr, car je peux toujours examiner les tableaux imbriqués ensuite. Je ne passe à un tableau enfant que lorsque ses éléments constituent réellement le jeu de données recherché.
Aplatir les objets JSON imbriqués
La gestion des objets imbriqués distingue un véritable convertisseur CSV d’un simple outil de transformation de fichiers.
Dans notre exemple, metrics est un objet :
{
"metrics": {
"employees": 124,
"revenue": {
"amount": 476171,
"currency": "USD"
}
}
}Dans un tableur, je ne veux pas d’une cellule metrics unique contenant un objet JSON. Je veux des colonnes que je peux filtrer et trier :
employeesamountcurrency
Datablist détecte les chemins des objets imbriqués et vous laisse choisir ceux à aplatir. Je conserve les champs scalaires utiles sous forme de colonnes, car ils sont plus faciles à exploiter dans les outils CSV.
Dans cet exemple, j’aplatis :
metrics.employeesenemployeesmetrics.revenue.amountenamountmetrics.revenue.currencyencurrency
Le CSV attendu au niveau des entreprises ressemble à ceci :
| Colonne CSV | Valeur source |
|---|---|
id | Identifiant de la ligne |
name | Nom de l’entreprise ou du compte |
website | Site web, tableau concaténé ou chaîne JSON selon les réglages |
contacts | Données de contact imbriquées avec une entreprise par ligne |
tags | Étiquettes concaténées ou texte d’origine |
employees | Valeur de metrics.employees |
amount | Valeur de metrics.revenue.amount |
currency | Valeur de metrics.revenue.currency |
createdAt | Date d’origine ou mise en forme |
Pour le premier export, je privilégie des noms de colonnes lisibles. Si le fichier contient des noms identiques dans plusieurs objets, vérifiez la prévisualisation avant le téléchargement. Par exemple, billing.amount et revenue.amount ne doivent pas tous deux être réduits à une colonne amount ambiguë sans vérification.
💡 Ma règle par défaut pour l’aplatissement
Aplatissez les champs scalaires que vous souhaitez filtrer, trier ou importer comme colonnes. Conservez les objets ou tableaux structurés au format JSON lorsque l’aplatissement ferait perdre leur sens ou produirait des cellules illisibles.
Gérer les tableaux dans les lignes JSON
Les tableaux exigent un choix spécifique : une cellule CSV contient du texte, tandis qu’un tableau JSON peut représenter des données très différentes.
Une liste de tags n’est pas comparable à une liste de contacts. Une liste d’adresses e-mail n’a pas la même fonction qu’une liste de lignes de commande. J’évite donc d’appliquer une règle unique lorsque les tableaux n’ont pas la même signification.
Pour notre fichier d’exemple, j’utiliserais les réglages suivants :
| Champ | Traitement recommandé | Pourquoi |
|---|---|---|
tags | Concaténer les valeurs | Les tags sont de simples étiquettes faciles à regrouper dans une cellule |
website | Concaténer les valeurs ou conserver le JSON | Concaténez pour gagner en lisibilité, ou gardez le JSON si les différences de structure comptent |
contacts | Conserver au format JSON pour les lignes d’entreprises | Les objets de contact possèdent leurs propres champs imbriqués |
contacts | Utiliser $.results[].contacts comme nœud pour les lignes de contacts | Solution préférable lorsque la liste de contacts est le résultat recherché |
Datablist propose plusieurs options pour traiter les tableaux : concaténer les valeurs, conserver les tableaux sous forme de chaînes JSON, prendre le premier élément ou appliquer des réglages au cas par cas.
Ma règle par défaut est simple :
- Concaténez les tableaux simples, comme les tags.
- Conservez les tableaux structurés sous forme de chaînes JSON si vous devez préserver leur contenu.
- Ne prenez le premier élément que s’il possède une signification claire, par exemple une adresse e-mail principale.
- Changez de nœud de lignes si chaque élément du tableau mérite sa propre ligne.
Pour l’export d’entreprises, je conserve contacts comme valeur structurée, car chaque contact possède un nom, des adresses e-mail et des numéros de téléphone. L’aplatir dans une cellule rendrait le CSV confus, tandis que ne garder que le premier contact entraînerait une perte de données.
Pour un export de contacts, je sélectionnerais plutôt $.results[].contacts. Le CSV contiendrait alors des colonnes propres aux contacts, telles que :
| Colonne CSV | Valeur source |
|---|---|
name | Nom du contact |
emails | Liste d’adresses e-mail concaténée ou chaîne JSON |
phones | Liste de numéros concaténée ou chaîne JSON |
Le compromis concerne le contexte. Un export d’entreprises conserve chaque entreprise dans une seule ligne. Un export de contacts se concentre sur les personnes, mais les champs de l’entreprise parente ne sont pas automatiquement recopiés dans chaque ligne de contact, sauf si l’outil prend en charge cette fonction dans une version ultérieure.
Configurer les options de sortie CSV
Une fois le nœud de lignes, l’aplatissement et le traitement des tableaux correctement configurés, réglez la sortie CSV.
Je commence généralement avec les options suivantes :
- Séparateur : point-virgule pour un CSV adapté aux usages français.
- Ligne d’en-tête : activée.
- Format de date : conserver le format d’origine, sauf si le tableur cible exige un format plus lisible.
Dans les configurations européennes, le point-virgule est souvent préférable, car la virgule sert généralement de séparateur décimal. Si votre tableur ou votre système cible attend un CSV séparé par des virgules, choisissez plutôt la virgule.
Pour les dates, je préfère conserver le format source lors du premier export. Les timestamps ISO sont faciles à analyser ensuite et préservent les informations de fuseau horaire. Si le CSV est destiné à un collègue non technique, vous pouvez toutefois mettre les dates en forme pour faciliter la lecture.
Avant le téléchargement, vérifiez les deux aperçus :
- L’aperçu sous forme de tableau permet de contrôler les lignes et les colonnes.
- L’aperçu du CSV brut permet de vérifier les séparateurs, les guillemets et les sauts de ligne.
🔑 Prévisualisez avant d’exporter
La prévisualisation permet de repérer un mauvais nœud de lignes, des colonnes manquantes, des tableaux illisibles ou un séparateur incorrect. Je préfère y consacrer 30 secondes plutôt que de devoir corriger ensuite un import défectueux dans un CRM ou un tableur.
Je vérifie systématiquement l’aperçu du CSV brut lorsque les données contiennent des tableaux ou du texte multiligne. Cela ne prend que quelques secondes et évite de nombreux problèmes d’import.
Vérifier et télécharger le CSV
Avant le téléchargement, je passe en revue cette checklist :
- Le nombre de lignes correspond-il au nœud sélectionné ?
- Les lignes représentent-elles bien l’entité recherchée ?
employees,amountetcurrencysont-ils répartis dans des colonnes utiles ?- Les tableaux sont-ils lisibles ou préservés au format JSON lorsque leur structure compte ?
- Les valeurs nulles de chiffre d’affaires sont-elles vides ou suffisamment claires pour l’étape suivante ?
- Les dates conviennent-elles au tableur ou à l’outil d’import ?
- L’aperçu du CSV brut utilise-t-il le séparateur attendu ?
Téléchargez ensuite le CSV. Lorsque vous importez un fichier, le nom du fichier téléchargé peut reprendre celui du fichier source, ce qui facilite la traçabilité.
Après l’export, ouvrez le fichier dans l’éditeur CSV de Datablist, Excel, Google Sheets ou votre prochain outil de données. Dans Datablist, vous pouvez poursuivre avec le nettoyage, le filtrage, la déduplication, l’enrichissement ou la traduction. Si vous générez plusieurs exports, vous pouvez comparer deux fichiers CSV. Si le fichier est trop volumineux pour un autre outil, vous pouvez diviser le CSV en fichiers plus petits.
Résultat CSV attendu
En sélectionnant $.results, vous obtenez principalement une entreprise ou un compte par ligne.
| Colonne CSV | Chemin JSON dans chaque ligne | Valeur attendue |
|---|---|---|
id | $.id | Identifiant de la ligne |
name | $.name | Nom de l’entreprise ou du compte |
website | $.website | Site web, tableau concaténé ou chaîne JSON |
contacts | $.contacts | Tableau de contacts concaténé ou au format JSON avec une entreprise par ligne |
tags | $.tags | Étiquettes concaténées ou chaîne d’origine |
employees | $.metrics.employees | Nombre de salariés |
amount | $.metrics.revenue.amount | Montant du chiffre d’affaires, lorsqu’il est disponible |
currency | $.metrics.revenue.currency | Devise du chiffre d’affaires, lorsqu’elle est disponible |
createdAt | $.createdAt | Date d’origine ou mise en forme |
En sélectionnant $.results[].contacts, vous obtenez une ligne par contact.
| Colonne CSV | Chemin JSON dans chaque contact | Valeur attendue |
|---|---|---|
name | $.name | Nom du contact |
emails | $.emails | Liste d’adresses e-mail concaténée ou chaîne JSON |
phones | $.phones | Liste de numéros concaténée ou chaîne JSON |
Les deux exports sont valides, mais ils répondent à des besoins différents.
Utilisez l’export au niveau des entreprises pour nettoyer des comptes, analyser des données firmographiques, enrichir des fiches d’entreprises ou préparer des imports CRM. Choisissez l’export au niveau des contacts lorsque les personnes constituent votre jeu de données cible.
Quand utiliser ce workflow
Ce workflow est utile dès que le JSON constitue le format source, mais que vous devez travailler en CSV.
Quelques cas d’usage :
- Réponses d’API avec des métadonnées, de la pagination et un tableau
resultsimbriqué. - Résultats de scraping via API contenant des annonces, des produits, des contacts ou des événements.
- Exports CRM et RevOps dans lesquels les entreprises contiennent des contacts, des tags, des métriques et des champs personnalisés.
- Exports de marketplaces ou de catalogues produits avec des variantes, des prix, des catégories et des fournisseurs.
- Logs de webhooks dont les événements sont imbriqués sous un payload.
- Workflows de localisation dans lesquels vous souhaitez traduire le CSV obtenu.
Le principe reste toujours le même : trouvez le tableau qui représente les lignes, aplatissez les champs objets utiles, choisissez comment traiter les tableaux, puis prévisualisez le résultat avant l’export.
Résoudre les problèmes de conversion JSON vers CSV
Si le JSON n’est pas valide, commencez par vérifier le fichier source. Des virgules manquantes, des logs de console copiés, du texte ajouté à la fin, un téléchargement incomplet ou des guillemets non échappés peuvent empêcher l’analyse. Je valide généralement le fichier avant de modifier les réglages de conversion, car un JSON invalide doit être corrigé à la source.
Si aucun nœud de lignes n’est détecté, le fichier ne contient peut-être pas de tableau d’objets. Un objet unique composé uniquement de champs scalaires ne suffit pas pour ce workflow. Les racines primitives, chaînes, nombres et valeurs uniques ne produisent pas de lignes CSV utiles.
Un nombre de lignes correct ne garantit pas que chaque champ soit devenu une colonne. Datablist détecte les colonnes à partir des 50 premiers enregistrements du nœud sélectionné, tandis que l’aperçu du tableau affiche jusqu’à 100 lignes. Par exemple, si seul l’enregistrement 51 possède un champ optional_note, le CSV peut contenir les 51 lignes sans inclure ce champ.
Recherchez dans la source les champs qui n’apparaissent que dans les enregistrements suivants et comparez-les aux en-têtes de sortie. Dans l’exemple précédent, placez une copie de l’enregistrement contenant optional_note parmi les 50 premiers, tout en conservant son ID et ses valeurs. Relancez la conversion, puis vérifiez que l’en-tête apparaît et que la note de l’enregistrement 51 est bien présente dans le CSV téléchargé. Comme le réordonnancement modifie l’ordre des lignes, utilisez les ID pour comparer le résultat et conservez le JSON d’origine. Pour les schémas très variables, assurez-vous que les 50 premiers enregistrements couvrent tous les champs nécessaires avant l’export.
Si l’aperçu affiche les mauvaises lignes, changez le nœud sélectionné. Cela signifie généralement que le convertisseur a trouvé un tableau, mais pas celui que vous aviez en tête. Recherchez le chemin où se trouvent les enregistrements, comme $.results, $.data.items ou $.payload.records.
Si les contacts, tags, lignes de commande ou événements sont difficiles à lire, modifiez le traitement des tableaux. Concaténez les listes simples. Conservez les tableaux structurés au format JSON pour préserver les détails. Passez à un nœud enfant lorsque chaque élément imbriqué doit devenir une ligne.
Si un fichier volumineux semble lent, gardez à l’esprit que les performances du navigateur et de l’appareil restent déterminantes. Datablist exécute l’analyse et la conversion dans un web worker : le traitement ne bloque donc pas le thread principal de l’interface, mais votre mémoire et votre processeur locaux imposent toujours des limites pratiques.
Si le CSV ne s’importe pas correctement dans un autre outil, essayez un séparateur différent, laissez la ligne d’en-tête activée et inspectez l’aperçu du CSV brut. Les guillemets et les sauts de ligne peuvent avoir leur importance lorsque les valeurs JSON contiennent du texte, des tableaux ou des objets imbriqués.
Ce qui se passe dans le navigateur
Datablist analyse et convertit le JSON dans un worker du navigateur. Celui-ci examine les nœuds de lignes candidats, met l’objet analysé en cache, convertit le nœud sélectionné en CSV, puis renvoie l’aperçu et le résultat à l’interface.
Cela compte pour deux raisons.
D’abord, la conversion ne s’exécute pas sur le thread principal de l’interface. La page reste ainsi utilisable pendant l’analyse du fichier.
Ensuite, le traitement s’effectue localement dans votre navigateur, sans envoi du fichier aux serveurs de Datablist pour la conversion. C’est particulièrement utile avec des exports d’API, des résultats de scraping ou des fichiers de données internes que vous ne souhaitez pas transmettre à un convertisseur côté serveur.
Continuez néanmoins à respecter vos règles habituelles de gestion des données. Le traitement local dans le navigateur est utile, mais il ne remplace pas les politiques de confidentialité et de conformité de votre entreprise.
Conclusion
La conversion d’un JSON imbriqué en CSV repose avant tout sur le choix du bon nœud de lignes. Une fois le tableau destiné à devenir les lignes sélectionné, la suite est beaucoup plus simple.
Dans notre exemple, $.results produit une entreprise par ligne. L’aplatissement de metrics.employees, metrics.revenue.amount et metrics.revenue.currency crée des colonnes faciles à exploiter dans un tableur. Les réglages des tableaux déterminent si des champs comme tags, website et contacts deviennent du texte lisible, du JSON préservé ou un export distinct au niveau des contacts.
Ouvrez le convertisseur JSON vers CSV, importez votre export JSON imbriqué, sélectionnez le nœud de lignes, vérifiez l’aperçu et téléchargez le CSV. Ouvrez ensuite le fichier exporté dans l’éditeur CSV de Datablist si vous souhaitez le nettoyer, le filtrer, le dédupliquer, l’enrichir ou le traduire.






