The Practical Way to Deep Nested JSON to Flat CSV

If you've ever stared at a JSON file with objects nested three or four levels deep and thought, "I just need this in a spreadsheet," you know the pain. Manually flattening nested arrays and objects is tedious, error-prone, and a total time sink. But here's the thing: you don't need to write a custom script or upload your data to some random server. There's a way to flatten deep nested JSON to flat CSV right in your browser, without your file ever leaving your device.

In this walkthrough, I'll show you how to use Toolkite's JSON ↔ CSV Converter to flatten nested JSON into a clean, flat CSV—step by step. We'll also look at a command-line alternative for when you need more control, and I'll point out the trade-offs so you can pick what fits your workflow.

Why Flatten Nested JSON Is a Headache

Let's be honest: JSON is great for APIs, but it's not exactly spreadsheet-friendly. A typical API response might look like this:

{
  "order_id": 12345,
  "customer": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "address": {
      "city": "Portland",
      "zip": "97205"
    }
  },
  "items": [
    {"sku": "A1", "qty": 2},
    {"sku": "B2", "qty": 1}
  ]
}

To get that into a CSV, you need to decide how to represent customer.address.city and the items array. Most converters either choke on the nesting or just give you a mess of [object Object]. That's why you need a tool that knows how to flatten nested structures into columns like customer.name, customer.address.city, and so on.

How to Flatten Deep Nested JSON to Flat CSV in 5 Steps

Here's the exact workflow I use with Toolkite's converter. It's free for files up to 25MB and handles nesting up to 10 levels, which covers most real-world API payloads.

Step 1: Open the Converter and Paste or Upload Your JSON

Head over to the JSON ↔ CSV Converter. You'll see a text area where you can paste your JSON directly. If your JSON is in a file, just drag and drop it—no upload, no waiting. The tool processes everything locally in your browser, so your data never touches a server.

Step 2: Choose the Right Conversion Mode

You'll want to select JSON → CSV. If you're aiming for an Excel file instead, you can pick JSON → Excel (which gives you an .xlsx). For this guide, we'll stick with CSV.

Step 3: Flatten the Nested JSON (Pro Feature)

Here's the key: to flatten nested objects and arrays, you need the Flatten nested JSON option, which is part of Toolkite Pro. With Pro, you get deep flattening that turns nested structures into column headers like customer.address.city. The free version handles flattening up to 10 levels, but Pro removes that limit and gives you more control.

If you're only dealing with a shallow structure (a couple of levels), the free version might be enough. But for deep nesting—say, an API response with three or four levels—Pro is worth the one-time $9.99.

Step 4: Convert and Preview

Hit the convert button. The tool will process the JSON and show you the resulting CSV. You'll see columns for each flattened path, and rows for each object. If your JSON has arrays, the tool will repeat the parent data for each array element—a common approach that keeps everything in a flat table.

Step 5: Download or Copy the Result

Once you're happy with the preview, click Download to save the CSV file, or just copy the output to your clipboard. That's it. No sign-up, no upload, no server-side processing.

What About Arrays of Objects?

If your JSON is an array of objects (like a list of users), the converter handles that fine. Each object becomes a row, and nested fields become columns. If you have arrays inside objects, the tool will “explode” them—meaning it creates multiple rows for each item in the array, duplicating the parent fields. That's the standard way to flatten nested JSON to CSV, and it works well for most use cases.

Alternative: Using jq and a Spreadsheet (CLI Approach)

If you're comfortable with the command line, you can flatten nested JSON using jq and then import the result into Excel or Google Sheets. For example, to flatten a simple object with one level of nesting, you might use:

jq -r '. as $root | .items[] | [.sku, .qty, $root.order_id, $root.customer.name] | @csv' data.json

That gets messy fast with deeper nesting. You'd have to write complex jq filters or switch to a tool like pandas in Python. The trade-off is control: you can decide exactly how to flatten, rename columns, and handle edge cases. But it requires scripting knowledge and debugging time.

The browser tool, on the other hand, is instant and doesn't require any setup. For a one-off conversion, it's usually faster. For a recurring pipeline, a script might be worth the investment.

Privacy: Your Data Stays in Your Browser

One thing I really appreciate about Toolkite is that everything runs locally. When you use the JSON ↔ CSV Converter, your JSON is processed in your browser using libraries like PapaParse and SheetJS. There's no file upload, so sensitive data—customer info, internal API responses, whatever—never leaves your machine. That's a big deal if you're handling data under NDA or just prefer not to trust random online tools.

If you're curious about the privacy details, you can read more on the privacy page.

When to Go Pro

The free tier is generous: files up to 25MB and flattening up to 10 levels. That covers a lot of cases. But if you're dealing with deeply nested JSON (more than 10 levels), files larger than 25MB, or you need to batch-convert multiple files, Pro is a one-time $9.99 purchase. It also removes ads and adds features like custom delimiters and API URL fetching. For a freelancer or developer who regularly wrestles with API data, it's a solid investment.

Final Thoughts

Flattening deep nested JSON to CSV doesn't have to be a chore. With the right browser tool, you can do it in minutes, without uploading your data anywhere. Next time you're staring at a nested API response, give the JSON ↔ CSV Converter a try. Your future self will thank you.

FAQ

What does flatten nested JSON mean?

Flattening nested JSON means converting a hierarchical structure (objects within objects, arrays) into a flat table where each column represents a path, like 'customer.address.city'. This makes it easy to view in a spreadsheet or import into a database.

Can I flatten deeply nested JSON for free?

Yes, Toolkite's JSON ↔ CSV Converter is free for files up to 25MB and supports flattening up to 10 levels of nesting. If your JSON is deeper than that, you'll need the Pro version, which costs a one-time $9.99.

Does Toolkite upload my JSON to a server?

No. The conversion happens entirely in your browser using client-side libraries. Your data never leaves your device, which is great for privacy-sensitive information.

How does the tool handle arrays inside nested objects?

When flattening, arrays are typically 'exploded'—each array element becomes a separate row, with the parent object's fields repeated. This produces a flat CSV where every row is self-contained.

Can I convert nested JSON to Excel (.xlsx) instead of CSV?

Yes. The Toolkite converter offers a JSON → Excel mode that produces an .xlsx file. The same flattening logic applies, so you can get a spreadsheet with nested fields as columns.

What are the limitations of the free version?

The free version supports files up to 25MB and flattening up to 10 levels. It also shows ads. Pro removes ads, increases the file limit to 50MB, allows deeper flattening, and adds batch conversion and custom delimiters.