JSON to CSV

What is JSON to CSV Conversion?

JSON to CSV conversion transforms structured data from JSON format into comma-separated values, a tabular format that spreadsheets, databases, and analytics tools consume natively. JSON stores data as nested objects and arrays with no fixed schema. CSV stores data as rows and columns with a header row defining field names. The conversion is how API data reaches spreadsheets and databases.

CSV (Comma-Separated Values) is defined by RFC 4180. Each line is one record, and fields within a line are separated by a delimiter character, most commonly a comma. Fields containing the delimiter, double quotes, or line breaks must be enclosed in double quotes, with internal quotes escaped by doubling them. This escaping is the primary source of bugs when writing a JSON-to-CSV converter by hand.

The conversion is straightforward when your input is a flat array of objects with consistent keys. Each object becomes one row, and each unique key becomes a column header. Nested objects and arrays require a flattening step, and inconsistent keys across objects require a strategy for handling missing fields — typically leaving the cell empty. A reliable converter handles all of these edge cases automatically.

Why Convert JSON to CSV?

APIs return JSON, but spreadsheets, SQL databases, and BI tools expect tabular data. Converting JSON to CSV lets you move data between these systems without writing custom import scripts.

JSON to CSV Use Cases

CSV Delimiter Reference

The delimiter character separates fields within each row. Comma is the most common, but other delimiters are standard in specific contexts. Choosing the wrong delimiter causes fields to merge or split incorrectly when the file is opened.

Handling Nested JSON in CSV

CSV is a flat format with no native way to represent nested objects or arrays. When your JSON contains nested structures, the converter must flatten them into columns. There are several strategies, and the right choice depends on how the CSV will be consumed.

Code Examples

Converting JSON to CSV programmatically requires handling header extraction, field quoting, and delimiter escaping. Most languages have built-in or standard library support for CSV writing.

const data = [
  { name: "Alice", age: 30, city: "Berlin" },
  { name: "Bob", age: 25, city: "Tokyo" },
]

// Extract headers from the first object
const headers = Object.keys(data[0])
const csv = [
  headers.join(","),
  ...data.map(row => headers.map(h => {
    const val = String(row[h] ?? "")
    // Quote fields that contain commas, quotes, or newlines
    return val.includes(",") || val.includes('"') || val.includes("\n")
      ? '"' + val.replace(/"/g, '""') + '"'
      : val
  }).join(","))
].join("\n")

console.log(csv)
// → name,age,city
// → Alice,30,Berlin
// → Bob,25,Tokyo

import json, csv, io

json_str = '[{"name":"Alice","age":30,"city":"Berlin"},{"name":"Bob","age":25,"city":"Tokyo"}]'
data = json.loads(json_str)

output = io.StringIO()
writer = csv.DictWriter(output, fieldnames=data[0].keys())
writer.writeheader()
writer.writerows(data)

print(output.getvalue())
# → name,age,city
# → Alice,30,Berlin
# → Bob,25,Tokyo

# Using jq to convert JSON array to CSV
echo '[{"name":"Alice","age":30},{"name":"Bob","age":25}]' | \
  jq -r '(.[0] | keys_unsorted) as $k | $k, (.[] | [.[$k[]]] ) | @csv'
# → "name","age"
# → "Alice",30
# → "Bob",25

# Using Miller (mlr) for streaming conversion
echo '[{"name":"Alice","age":30}]' | mlr --json --ocsv cat
# → name,age
# → Alice,30

package main

import (
    "encoding/csv"
    "encoding/json"
    "fmt"
    "os"
)

func main() {
    jsonStr := `[{"name":"Alice","age":30},{"name":"Bob","age":25}]`
    var data []map[string]interface{}
    json.Unmarshal([]byte(jsonStr), &data)

    w := csv.NewWriter(os.Stdout)
    // Write header
    headers := []string{"name", "age"}
    w.Write(headers)
    // Write rows
    for _, row := range data {
        record := make([]string, len(headers))
        for i, h := range headers {
            record[i] = fmt.Sprintf("%v", row[h])
        }
        w.Write(record)
    }
    w.Flush()
    // → name,age
    // → Alice,30
    // → Bob,25
}

Frequently Asked Questions