Tutorial · 5 min read
How to Convert JSON Array of Objects to CSV with Headers
JSON APIs return arrays of objects. Your spreadsheet needs clean column headers. A JSON to CSV converter bridges the gap — turning object keys into column names and values into rows in seconds.
1. Understanding JSON Array of Objects Structure
Most JSON APIs return data as an array of objects. Each object has the same set of keys, making it a natural fit for CSV conversion:
[
{"id": 1, "name": "Alice", "email": "alice@example.com"},
{"id": 2, "name": "Bob", "email": "bob@example.com"},
{"id": 3, "name": "Charlie", "email": "charlie@example.com"}
]
Result: The keys id, name, email become column headers. Each object becomes a row. No mapping needed — it works automatically when you paste into the converter.
2. How Column Headers Are Generated
The converter reads all unique keys from every object in the array and uses them as column headers. For nested objects, headers use dot notation:
[
{"name": "Alice", "address": {"city": "Beijing", "zip": "100000"}},
{"name": "Bob", "address": {"city": "Shanghai", "zip": "200000"}}
]
Becomes headers: name, address.city, address.zip
This means even deeply nested APIs produce clean, readable column names in your spreadsheet.
3. Handling Arrays with Missing or Extra Fields
Real-world JSON often has objects with different fields. The converter handles this gracefully:
[
{"id": 1, "name": "Alice", "phone": "123-456"},
{"id": 2, "name": "Bob"}
]
Result: All unique keys become columns. Missing fields get empty cells. The converter collects headers from all objects, not just the first one, so no column is lost.
4. Converting NDJSON (JSON Lines) to CSV
Newline-Delimited JSON (NDJSON) is a streaming format where each line is a complete JSON object:
{"id":1,"name":"Alice","role":"admin"}
{"id":2,"name":"Bob","role":"user"}
{"id":3,"name":"Charlie","role":"editor"}
Tip: The converter auto-detects NDJSON format. No special configuration needed — just paste it in and it treats each line as a row.
5. Choosing the Right Delimiter and Encoding
CSV stands for "comma-separated values," but your target application may need a different delimiter:
| Delimiter | Best For | Notes |
|---|---|---|
| Comma (,) | General purpose | Standard CSV format |
| Semicolon (;) | European Excel | Locale default for many countries |
| Tab | Database imports | Avoids comma conflicts in text |
| Pipe (|) | Data processing | Rarely appears in data |
Excel tip: Use UTF-8 BOM encoding with CRLF line endings for the best Excel compatibility. The converter's config bar has these as one-click options.
Try the Free JSON to CSV Converter
Paste a JSON array and see clean CSV with proper headers instantly. Edit cells, choose delimiters, and download.
Convert JSON to CSV Now →Best Practices for JSON Array to CSV Conversion
- Use consistent keys. Objects with the same keys produce cleaner column headers. If keys vary, the converter collects all unique keys but some cells will be empty.
- Choose the right flattening mode. For nested objects, our nested JSON to CSV guide covers three flattening modes in detail.
- Check the table preview first. Always review the live preview before downloading — verify headers look correct and no columns are missing.
- Use UTF-8 BOM for Excel. If you're opening the CSV in Excel, switch the encoding to UTF-8 BOM to avoid garbled characters.
- Repair broken JSON first. If your API response has syntax errors, use the JSON Repair guide to fix them before converting.
Frequently Asked Questions
How do I convert a JSON array of objects to CSV with headers?
Paste your JSON array into a JSON to CSV converter. The tool automatically reads object keys as column headers and maps each object's values into rows.
How are column headers generated from JSON?
Column headers are derived from the keys of every object in the array. All unique keys across all objects become column headers.
How do I handle JSON arrays with missing fields?
Missing fields produce empty cells. The JSON to CSV Converter collects headers from all objects, so no column is ever lost.
What delimiter should I use for CSV?
Comma is standard. Use semicolon for European Excel locales, Tab for database imports, and Pipe for data processing pipelines.
Why are my CSV columns showing garbled text in Excel?
Switch encoding to UTF-8 BOM and line endings to CRLF in the tool's config bar. This ensures Excel correctly interprets the character encoding.
Looking for more guides? See the full JSONXX How To index.