JSON to CSV: How to Convert Data Between Formats

JSON and CSV are two of the most common data formats. JSON is the standard for APIs and configuration files. CSV is the standard for spreadsheets and data analysis. Converting between them is a task every developer and data analyst encounters regularly.

This guide explains the differences between JSON and CSV, shows you how to convert between them in code, and provides a free online tool for instant conversion.

For a quick browser-based workflow, use the JSON to CSV Converter after cleaning your input with the JSON Formatter & Validator.

What Is JSON?

JSON (JavaScript Object Notation) is a lightweight data interchange format. It uses human-readable text to store and transmit data objects consisting of key-value pairs and arrays.

[
  {
    "name": "Alice",
    "age": 30,
    "city": "New York",
    "skills": ["Python", "JavaScript"]
  },
  {
    "name": "Bob",
    "age": 25,
    "city": "London",
    "skills": ["Java", "Go"]
  }
]

What Is CSV?

CSV (Comma-Separated Values) is a plain text format where each line represents a data record and each field is separated by a comma.

name,age,city,skills
Alice,30,New York,"Python; JavaScript"
Bob,25,London,"Java; Go"

Key Differences

Converting JSON to CSV

Python

import json
import csv

with open('data.json', 'r') as f:
    data = json.load(f)

if data:
    keys = data[0].keys()
    with open('output.csv', 'w', newline='') as f:
        writer = csv.DictWriter(f, fieldnames=keys)
        writer.writeheader()
        writer.writerows(data)

JavaScript (Node.js)

const fs = require('fs');

const data = JSON.parse(fs.readFileSync('data.json', 'utf8'));

if (data.length > 0) {
  const headers = Object.keys(data[0]);
  const rows = data.map((row) => headers.map((h) => JSON.stringify(row[h] || '')).join(','));
  const csv = [headers.join(','), ...rows].join('\n');
  fs.writeFileSync('output.csv', csv);
}

PHP

$json = file_get_contents('data.json');
$data = json_decode($json, true);

$fp = fopen('output.csv', 'w');
if (!empty($data)) {
    fputcsv($fp, array_keys($data[0]));
    foreach ($data as $row) {
        fputcsv($fp, $row);
    }
}
fclose($fp);

Handling Nested JSON

The biggest challenge with JSON-to-CSV conversion is nested data. CSV is flat, but JSON can have deeply nested structures. Here are the two most common strategies.

Flatten with dot notation

Convert nested keys into flat column names:

{
  "name": "Alice",
  "address": {
    "street": "123 Main St",
    "city": "New York"
  }
}

Becomes:

name,address.street,address.city
Alice,123 Main St,New York

Handle arrays

Arrays within objects can be joined with a separator (like semicolons) or expanded into separate columns if the array length is known.

Our JSON to CSV Converter automatically flattens nested objects with dot notation and joins array values with semicolons, producing clean, importable CSV output without any manual preprocessing.

Choosing the Right Output Shape

Before converting, decide what the CSV will be used for. A spreadsheet review, a database import, and a business intelligence dashboard may need different shapes.

For simple reporting, one JSON object should usually become one CSV row. Nested fields can be flattened, and short arrays such as tags can live in one cell. This keeps the output compact and easy to open in Excel, Google Sheets, or a data-cleaning tool.

For transactional data, one object may contain many child records. An order can contain multiple line items, and a user can contain multiple sessions. Joining those child records into one cell may hide important detail. In that case, you may need two CSV files:

• one parent file, such as orders.csv
• one child file, such as order_items.csv

This is not a limitation of JSON. It is a limitation of trying to fit hierarchical data into a flat table. If the relationship matters, preserve it deliberately instead of letting a converter guess.

Data Quality Checks After Conversion

After converting JSON to CSV, do not only check that the file opens. Check whether the table still represents the original data accurately.

Review these points:

• Does the number of CSV rows match the number of source objects?
• Are all expected headers present?
• Did nested fields become predictable names such as profile.city?
• Did arrays become readable values rather than [object Object]?
• Are commas, quotes, and line breaks safely quoted?
• Did null values become empty cells, the word null, or another placeholder?

If the CSV will be imported into another system, test with a small sample first. A five-row test is enough to reveal most header, delimiter, encoding, and quoting problems before a full export causes cleanup work.

Also keep a copy of the original JSON. CSV is often a lossy review format. Once nested objects are flattened and arrays are joined, it may be hard to reconstruct the exact original document. If the conversion supports a business process, treat the CSV as an export, not as the only source of truth.

Example: API Response to Spreadsheet Review

Imagine an API returns customer records:

[
  {
    "id": "cus_1001",
    "email": "ada@example.com",
    "profile": { "country": "US", "plan": "Pro" },
    "tags": ["trial", "newsletter"]
  }
]

A useful CSV for review might look like:

id,email,profile.country,profile.plan,tags
cus_1001,ada@example.com,US,Pro,"trial; newsletter"

That output is not identical to the original JSON, but it is practical for filtering, sorting, and sharing. The important part is making the transformation rules visible so another person can understand where each column came from.

Common Pitfalls

1. Commas in data Values containing commas must be quoted in CSV. Proper converters handle this automatically.

2. Newlines in data Values with newlines must be quoted and may cause issues with some importers.

3. Encoding Use UTF-8 encoding to preserve special characters. Some tools default to ASCII.

4. Inconsistent keys If objects in the array have different keys, the converter should include all unique keys as headers.

Conclusion

JSON and CSV serve different purposes, but you often need to move data between them. For quick one-off conversions, use our free online tool. For automated workflows, the Python and JavaScript examples above give you a solid starting point. Always handle edge cases like nested objects, arrays, and special characters to avoid data loss during conversion.

Related QuickToolFlow Tools

• JSON to CSV Converter for converting arrays of objects into downloadable CSV files.
• JSON Formatter & Validator for checking JSON before conversion.
• Text Diff Checker for comparing CSV or JSON output after changes.