Converter JSON para CSV - Guia completo para iniciantes

A conversão de JSON para CSV é uma tarefa comum quando você precisa analisar dados JSON em aplicativos de planilha. O JSON (JavaScript Object Notation) é o formato dominante em APIs e armazenamento de dados, pois oferece suporte a estruturas aninhadas e a vários tipos de dados. Já o CSV (Comma-Separated Values, ou valores separados por vírgula) é o formato universal para planilhas, bancos de dados e ferramentas de análise. Converter entre os dois formatos conecta a troca de dados estruturados à análise tabular.

Por que converter JSON para CSV?

Existem várias razões práticas para converter dados JSON em formato CSV:

Importar dados para o Excel ou Google Sheets

Aplicativos de planilha abrem arquivos CSV nativamente, com colunas e linhas devidamente alinhadas. Já os arquivos JSON aparecem como texto bruto e exigem análise manual. Ao converter para CSV, você pode aproveitar os recursos de filtragem, classificação, gráficos e tabelas dinâmicas do Excel sem escrever nenhum código.

Usar ferramentas de análise de dados

Ferramentas como Tableau, Power BI, R e pandas no Python funcionam naturalmente com dados CSV. Embora consigam interpretar JSON, o CSV costuma ser mais rápido de carregar e mais fácil de inspecionar visualmente. Se o seu pipeline de ciência de dados espera uma entrada tabular, converter JSON para CSV é o primeiro passo.

Compartilhar dados com colegas não técnicos

Qualquer pessoa com um software de planilha pode abrir arquivos CSV, independentemente do seu conhecimento técnico. Enviar um arquivo JSON para alguém que não é desenvolvedor costuma gerar confusão. Converter para CSV torna seus dados imediatamente acessíveis a toda a equipe.

Reduzir o tamanho do arquivo em grandes conjuntos de dados

A sintaxe verbosa do JSON adiciona uma sobrecarga significativa por meio de chaves, colchetes, vírgulas e aspas repetidos. O CSV elimina a maior parte dessa redundância. Em grandes conjuntos de dados, a redução no tamanho do arquivo pode ser considerável, chegando muitas vezes a 30% a 50% ou mais. Isso torna os arquivos CSV mais rápidos de transferir, armazenar e processar.

Entendendo os requisitos de estrutura dos dados

Antes de converter, você precisa entender uma restrição importante: o CSV é um formato plano e bidimensional. Ele oferece suporte a linhas e colunas, mas não a objetos ou arrays aninhados. Se seus dados JSON contiverem estruturas aninhadas, você deve achatá-las durante a conversão. As estratégias de achatamento mais comuns incluem:

Notação de ponto: converta {"address": {"city": "Paris"}} em uma coluna chamada address.city.
Expansão de arrays: se um campo contiver um array, crie várias linhas, uma para cada elemento, duplicando os demais campos.
Serialização: armazene objetos aninhados como strings JSON dentro de uma única coluna CSV.

Ferramenta online

A ferramenta Conversor de JSON para CSV transforma arrays JSON em formato CSV com opções personalizáveis. Veja como usá-la:

Cole seu array JSON na área de entrada. A ferramenta espera um array de objetos, em que cada objeto representa uma linha.
Configure o separador (vírgula, ponto e vírgula ou tabulação) e o caractere de delimitação.
Escolha se deseja incluir cabeçalhos (derivados das chaves dos objetos).
Clique em converter e baixe o arquivo CSV resultante.

A ferramenta também lida com objetos aninhados, achatando-os com notação de ponto, e oferece uma prévia das primeiras linhas para que você verifique o resultado antes de baixar.

Conversão com JavaScript

Se você trabalha em um navegador ou em um ambiente Node.js, pode converter JSON para CSV programaticamente com JavaScript. Veja uma implementação robusta:

function jsonToCsv(json, delimiter = ',') {
  const items = typeof json === 'string' ? JSON.parse(json) : json;
  if (!items || !items.length) return '';

  // Extrai os cabeçalhos do primeiro objeto, tratando chaves aninhadas
  const getKeys = (obj, prefix = '') => {
    return Object.keys(obj).reduce((keys, key) => {
      const fullKey = prefix ? `${prefix}.${key}` : key;
      if (typeof obj[key] === 'object' && obj[key] !== null && !Array.isArray(obj[key])) {
        return keys.concat(getKeys(obj[key], fullKey));
      }
      return keys.concat(fullKey);
    }, []);
  };

  const headers = getKeys(items[0]);
  const escapeField = (value) => {
    const str = value === null || value === undefined ? '' : String(value);
    if (str.includes(delimiter) || str.includes('"') || str.includes('\n')) {
      return '"' + str.replace(/"/g, '""') + '"';
    }
    return str;
  };

  const csv = [
    headers.join(delimiter),
    ...items.map(item => {
      const getValue = (obj, key) => {
        const keys = key.split('.');
        let value = obj;
        for (const k of keys) {
          if (value === null || value === undefined) return '';
          value = value[k];
        }
        return escapeField(value);
      };
      return headers.map(h => getValue(item, h)).join(delimiter);
    })
  ];

  return csv.join('\n');
}

Essa implementação trata objetos aninhados, faz o escape adequado de campos que contêm separadores ou aspas e lida com valores ausentes sem problemas.

Conversão com Python

A biblioteca padrão do Python inclui tudo o que você precisa para converter JSON em CSV. O módulo json faz a leitura da entrada, e o módulo csv grava a saída com escape e aspas adequados.

import json
import csv

def json_to_csv(input_file, output_file):
    with open(input_file, 'r', encoding='utf-8') as f:
        data = json.load(f)

    if not data:
        print("No data found in input file")
        return

    # Extrai os cabeçalhos do primeiro objeto
    headers = list(data[0].keys())

    with open(output_file, 'w', newline='', encoding='utf-8') as f:
        writer = csv.DictWriter(f, fieldnames=headers)
        writer.writeheader()
        writer.writerows(data)

    print(f"Successfully converted {len(data)} rows to {output_file}")

# Uso
json_to_csv('data.json', 'output.csv')

Para dados JSON aninhados, você pode achatar a estrutura com uma função recursiva antes de gravar o CSV. A biblioteca pandas também oferece uma solução prática em uma única linha: pandas.read_json('data.json').to_csv('output.csv', index=False).

Linha de comando com jq

Para quem prefere a linha de comando, o utilitário jq é um poderoso processador de JSON capaz de converter arrays JSON em CSV com um único comando:

# Conversão básica
jq -r '(.[0] | keys_unsorted) as $keys | $keys, map([.[ $keys[] ]])[] | @csv' data.json

# Delimitador personalizado
jq -r '(.[0] | keys_unsorted) as $keys | $keys, map([.[ $keys[] ]])[] | @tsv' data.json

# Trata objetos aninhados selecionando campos específicos
jq -r '.[] | [.id, .name, .email] | @csv' data.json

As strings de formato @csv e @tsv fazem o escape automático de campos que contêm vírgulas, aspas ou quebras de linha. Para arquivos grandes, o jq é extremamente rápido porque processa o JSON em streaming, sem carregar o arquivo inteiro na memória.

Armadilhas comuns e soluções

Objetos aninhados

O maior desafio na conversão de JSON para CSV é lidar com objetos aninhados. Como o CSV não consegue representar dados hierárquicos, você precisa escolher uma estratégia de achatamento. A abordagem mais comum é a notação de ponto, em que cada campo aninhado se torna uma coluna separada com um nome pontuado.

Arrays dentro de objetos

Quando um objeto contém um campo do tipo array, você tem três opções:

Expandir linhas: crie uma linha por elemento do array, duplicando os demais campos.
Concatenar: una os elementos do array com um separador e armazene-os em uma única coluna.
Várias colunas: crie colunas separadas para cada índice do array, caso você saiba o comprimento máximo.

Tipos de dados mistos

Arrays JSON podem conter objetos com estruturas diferentes. O CSV exige um esquema uniforme em todas as linhas. A melhor abordagem é usar a união de todas as chaves de todos os objetos, preenchendo com valores vazios as chaves ausentes.

Conclusão

A conversão de JSON para CSV é um processo simples depois que você entende as diferenças estruturais entre os dois formatos. Seja qual for a sua preferência — um conversor online, uma linguagem de programação ou uma ferramenta de linha de comando —, você tem muitas opções à disposição. Para conversões pontuais e rápidas, a ferramenta online Conversor de JSON para CSV é a escolha mais fácil. Para fluxos de trabalho automatizados, os exemplos com JavaScript, Python e jq acima oferecem uma base sólida para você começar.

Converter JSON para CSV – Guia para iniciantes