How to Flatten Nested JSON โ JavaScript & Python Examples
Published: July 20, 2025 ยท Last updated: September 7, 2026 ยท 6 min read ยท By JSON Suite Team
Nested JSON is easy to read but hard to process. When loading data into a spreadsheet, database table, or analytics tool, you often need a flat structure โ one level of keys with no nested objects. This guide shows you how to flatten JSON in both JavaScript and Python. If you're new to JSON, start with our guide on what JSON is first.
What Does "Flattening" Mean?
Flattening converts nested keys into dot-separated (or underscore-separated) keys at the top level.
Flatten JSON in JavaScript
A recursive function that walks every key and builds dot-notation paths:
Handling Arrays During Flattening
Arrays can be treated in two ways: keep them as-is (default above), or expand each element with an index key.
Flatten JSON in Python
Using pandas.json_normalize (Python)
If you're already using pandas, json_normalize flattens JSON into a DataFrame in one line.
The sep parameter controls the separator character (default is .). Use sep="_" for underscore-separated keys that work better as DataFrame column names.
Unflattening โ Reverting to Nested
Sometimes you need the reverse operation โ rebuilding a nested structure from flat keys:
Common Use Cases for Flattening
Flattening nested JSON is essential in many scenarios. When working with APIs that return deeply nested responses, you may need flat data for CSV export or database storage. Data analysts often flatten JSON for use in spreadsheets or SQL databases. If you're dealing with JSON parsing errors, flattening can help simplify debugging by revealing the full key paths.
Performance Considerations
For large JSON documents, recursive flattening can be memory-intensive. Consider using streaming approaches when processing files over 100MB. Our JavaScript parsing guide covers performance optimization techniques including Web Workers for heavy JSON operations. Python users can refer to our Python JSON guide for efficient handling of large datasets.
Try Our JSON Tools
Want to explore nested JSON before writing code to flatten it?
- JSON Tree Viewer โ visualize nesting depth interactively
- JSON Path Tester โ extract nested values with JSONPath expressions
- JSON to CSV Converter โ auto-flattens JSON for spreadsheet export