How to Convert JSON to CSV: A Complete Guide

If you work with APIs, databases, or any modern web service, you've almost certainly encountered JSON. It's the lingua franca of data exchange on the web. But when it comes time to analyze that data in Excel, import it into a database, or share it with someone who doesn't speak JSON, you need CSV.

The conversion sounds simple — and for flat data, it is. But real-world JSON is rarely flat. This guide covers everything you need to know to convert JSON to CSV reliably, whether you're dealing with a simple array or deeply nested API responses.

Why Convert JSON to CSV?

JSON and CSV serve different purposes. JSON excels at representing complex, hierarchical data. CSV excels at representing tabular data — rows and columns. The need to convert usually comes from one of these scenarios:

Spreadsheet analysis. Your team lead wants the API data in Excel. Analysts think in rows and columns, not in nested objects and arrays. CSV opens directly in any spreadsheet application.

Database imports. Most relational databases have built-in CSV import tools. Importing JSON typically requires custom scripts or ETL pipelines. CSV is the path of least resistance.

Reporting tools. Business intelligence tools like Tableau, Power BI, or Looker work natively with tabular formats. Getting your JSON into CSV is often the first step toward a dashboard.

Human readability. A CSV file can be opened in any text editor and understood at a glance. JSON with 5 levels of nesting? Not so much.

The Simple Case: Flat JSON

When your JSON is a flat array of objects with consistent keys, the conversion is straightforward. Each object becomes a row, and each key becomes a column header.

[
  { "name": "Alice", "age": 30, "city": "Paris" },
  { "name": "Bob", "age": 25, "city": "London" },
  { "name": "Charlie", "age": 35, "city": "Berlin" }
]

Becomes:

name,age,city
Alice,30,Paris
Bob,25,London
Charlie,35,Berlin

No surprises here. But most real-world JSON doesn't look this clean.

The Hard Part: Nested Objects

This is where most converters either fail or produce unreadable output. Consider a typical API response:

[
  {
    "id": 1,
    "name": "Alice",
    "address": {
      "street": "123 Rue de Rivoli",
      "city": "Paris",
      "country": "France"
    },
    "tags": ["developer", "manager"]
  }
]

There are two common strategies for handling nested data.

Dot notation flattening takes each nested key and creates a column by joining the path with dots. So address.street, address.city, and address.country each become their own column. This preserves all your data and keeps it queryable. It's the approach most professional tools use.

Stringification converts the nested object to a JSON string and dumps it into a single cell: {"street":"123 Rue de Rivoli","city":"Paris","country":"France"}. It's technically lossless, but it defeats the purpose of converting to CSV in the first place — you still have JSON sitting inside your spreadsheet cells.

For arrays like tags, you'll typically see them joined into a single string ("developer, manager") since CSV has no concept of multi-value cells.

Common Pitfalls

A few things that trip people up when converting JSON to CSV:

Inconsistent keys across objects. Not every object in your array will have the same fields. A good converter scans all objects to build the complete set of column headers, then fills in empty cells where a field is missing from a particular object.

Special characters in values. Commas, quotes, and newlines inside your data can break CSV parsing if they're not properly escaped. The CSV spec requires that fields containing these characters be wrapped in double quotes, and any double quotes inside the field be doubled (""). This is handled automatically by proper tools, but it's a common source of bugs in hand-rolled solutions.

Large files and memory. JSON requires the entire file to be loaded into memory for parsing. If you're converting a 500MB JSON file, you need at least that much free RAM — more, actually, since the parsed data structure uses more memory than the raw text. For very large files, consider streaming parsers or splitting the JSON first.

Encoding issues. JSON is always UTF-8. CSV files, especially ones destined for Excel, sometimes need a BOM (byte order mark) at the beginning to display non-ASCII characters correctly. If you see garbled accented characters in Excel after opening your CSV, this is usually why.

Methods for Converting

Online Tools

The fastest option for one-off conversions. Paste your JSON, get CSV back. The key things to look for: client-side processing (your data stays in your browser), nested object support, and the ability to handle large inputs without crashing.

Python

Python with pandas is the go-to for developers:

import pandas as pd

df = pd.read_json("data.json")
df.to_csv("output.csv", index=False)

For nested JSON, use pd.json_normalize() which handles dot notation flattening automatically:

df = pd.json_normalize(data, sep=".")

Command Line

jq is the Swiss army knife for JSON on the command line:

jq -r '(.[0] | keys_unsorted) as $cols | $cols, map([.[$cols[]]])[] | @csv' data.json > output.csv

Not the most readable command, but it works without installing anything beyond jq itself.

JavaScript / Node.js

If you're already in a JavaScript environment, libraries like papaparse (for the browser) or json2csv (for Node) handle the conversion cleanly, including nested object flattening and proper CSV escaping.

Choosing the Right Method

It depends on your workflow. If you need a quick one-time conversion and don't want to write code, an online tool is your best bet. If you're building this into a pipeline, Python or Node.js give you more control. If you're on a server with no GUI, jq on the command line works great.

The main thing to watch out for is how each method handles nested objects and edge cases. Test with your actual data before committing to a solution — the simple examples in documentation rarely reflect the messiness of real-world JSON.

Wrapping Up

Converting JSON to CSV is one of those tasks that's simple in theory and surprisingly nuanced in practice. The key decisions are how to handle nested structures (flatten with dot notation or stringify), how to deal with inconsistent keys across objects, and making sure special characters are properly escaped.

For most use cases, you don't need to write code — a good online converter handles all of this automatically. The important thing is choosing one that processes your data locally, handles nested objects intelligently, and doesn't choke on large files.