--- title: "JSON Flatten" description: "Flatten nested JSON into a CSV whose columns are dot paths such as address.city. A data, results, items or records wrapper is found for you, arrays are joined or spread into columns, and on this page the JSON stays in your browser." url: https://findutils.com/convert/json-flatten/ category: convert --- # JSON Flatten Flatten nested JSON into a CSV whose columns are dot paths such as address.city. A data, results, items or records wrapper is found for you, arrays are joined or spread into columns, and on this page the JSON stays in your browser. **Use this tool:** [JSON Flatten](https://findutils.com/convert/json-flatten/) ## Programmatic access - REST id `json-flatten`: POST https://api.findutils.com/api/tools/json-flatten/execute (reference: https://findutils.com/api/json-flatten/) - MCP tool `json_flatten` on https://mcp.findutils.com (reference: https://findutils.com/mcp/json-flatten/) - Data: The REST API and the MCP tool are a separate path from this page: a call sends the input you include to FindUtils over HTTPS, where it is processed and the result returned. FindUtils does not store that input, and logs the request without its content. ## Why Use JSON Flatten? API responses nest their data: a user carries an address object, an order carries a customer and a list of lines. A spreadsheet wants one value per cell, so address.city and address.zip have to become columns of their own. The JSON to CSV converter keeps a nested object as JSON text in one cell on purpose, and the usual way out is a jq filter or a short script. This page does the flatten step in one paste: it finds the array of records, even inside a data or results wrapper, writes every nested key as a dot-path column, unions the columns across rows, and gives you an RFC 4180 CSV to download. Each row is flattened by run() from the json_flatten module, the code behind the REST API and the MCP tool, so a nested object gets the same dot-path name on the page and over the API. ## JSON Flatten Tips - The header is the union of every flattened key across every row, in the order the keys first appear. A row without a key gets an empty cell there, and so does null. - Join with | writes ["admin","beta"] as admin|beta. If your values can contain a pipe themselves, use JSON cell, which keeps the array exactly as JSON text. - An array of objects, such as order lines, stays JSON text under Join with |. Indexed columns spreads it into lines[0].sku, lines[1].sku and so on, one column per position. - An empty object produces no column. If a field is an empty object on every row, it does not appear in the CSV. - Whole numbers above 9007199254740991 lose precision in any JavaScript JSON parser, this page included. If your IDs are that long, have the API send them as strings. ## Frequently Asked Questions ### What does JSON Flatten do? JSON Flatten turns nested JSON into a flat CSV in which every nested key becomes its own column, named by its dot path. A record such as {"id":1,"address":{"city":"London"}} becomes the columns id and address.city. Paste or drop the JSON, and the CSV appears as soon as it parses, ready to copy or download. ### How is JSON Flatten different from JSON to CSV? The [JSON CSV Converter](https://findutils.com/convert/json-to-csv/) writes a nested object or array as JSON text in one cell, while JSON Flatten spreads it into dot-path columns. Use the converter when one column per top-level key is what you want, and JSON Flatten when the spreadsheet needs address.city and address.zip as separate columns. ### Which part of my JSON becomes the rows? A top-level array gives one row per object. If the top level is an object, the array under data, results, items or records is used, or one level below them, such as data.items. Anywhere else, type the path in Array path, for example response.users or pages[0].rows. A single object with no such array becomes one row. ### How are arrays written? Join with |, the default, writes a list of plain values in one cell, so ["admin","beta"] becomes admin|beta, and keeps an array of objects as JSON text. JSON cell writes every array as JSON text. Indexed columns spreads arrays into columns such as tags[0], tags[1] and lines[0].sku. No mode turns array items into extra rows. ### What does the Depth setting do? Depth limits how many dot segments a column name may have. With 2 levels, address.city becomes a column but address.geo.lat stays inside an address.geo column as JSON text. All levels, the default, flattens everything. ### What happens to null, missing keys and empty objects? null and a missing key both write an empty cell, because CSV has no null. The header is the union of every key in every row, in the order the keys first appear, so a key that only one row has still gets a column. An empty object produces no column, and under Join with | an empty array is an empty cell. ### Can I flatten JSON Lines (NDJSON or .jsonl)? Not on this page. JSON Lines holds one object per line and is not one JSON document, so it fails to parse here. [NDJSON to CSV](https://findutils.com/convert/ndjson-to-csv/) reads that format and flattens each line with the same dot paths. When a paste looks like JSON Lines, the error message links there. ### Can I turn the flat CSV back into nested JSON? Not on this page. The json_unflatten REST API and MCP tool rebuild nested JSON from a flat key map such as {"address.city":"London"}. A CSV that has been through a spreadsheet can lose the value types and the column names a full round trip needs, so this page does not promise one. ### Is my JSON uploaded? On this page, no. The JSON is parsed and the CSV is built in your browser, and the page sends no request with your data; you can confirm that in the network panel while converting. The REST API and MCP tool are a separate path: a call sends the input you include to FindUtils over HTTPS, where it is processed and the result returned. FindUtils does not store that input, and logs the request without its content. ### Is there an API for flattening JSON? Yes, for the flattening step. The json_flatten REST API and MCP tool take one JSON object and return a flat key map with the same dot paths for nested objects. By default the REST API writes an array position as items.0 and the MCP tool as items[0], the form this page uses. They do not write CSV: finding the array, the array modes, the depth limit and the CSV itself are on this page. ### How large a JSON file can I flatten? The page accepts up to 10 MB of JSON. The work runs in your tab, so a file near the cap can keep the browser busy for a moment. When the CSV has more than 2,000 lines, the output panel shows the first 200, and Copy and Download still use the whole CSV. ### Will the CSV open correctly in Excel or Google Sheets? Yes. Google Sheets and Numbers read the UTF-8 file as it is. Excel on Windows can show accented letters wrongly in a plain UTF-8 CSV; turn on Excel BOM before you download. If your Excel expects semicolons, choose the semicolon separator. ## Related Tools - [JSON to CSV](https://findutils.com/convert/json-to-csv/) - [NDJSON CSV Converter](https://findutils.com/convert/ndjson-to-csv/) - [JSON to Markdown Table](https://findutils.com/convert/json-to-markdown-table/) - [JQ Playground](https://findutils.com/developers/jq-playground/) - [JSON Formatter](https://findutils.com/developers/json-formatter/) - [CSV Viewer](https://findutils.com/convert/csv-viewer/) - [JSON Diff](https://findutils.com/developers/json-diff/)