Need to convert nested JSON into flat key-value pairs? This guide covers everything you need to know about JSON flattening via API, including different notations and implementation examples in multiple languages.
What is JSON Flattening?
JSON flattening converts nested objects into a flat structure with compound keys. Each nested path becomes a single key, making complex data easier to work with in certain contexts.
For example, {"user": {"name": "John"}} becomes {"user.name": "John"} when flattened with dot notation.
Notation Styles
Different styles for representing nested paths:
Dot Notation
user.address.city - Most common, easy to read. Used by many ORMs and config systems.
Bracket Notation
user[address][city] - Compatible with query strings and form data.
Array Indexing
users.0.name or users[0].name - How array elements are represented.
Using the JSON Flatten API
TinyFn provides endpoints to flatten and unflatten JSON:
POST https://api.tinyfn.io/v1/json/flatten
Headers: X-API-Key: your-api-key
Content-Type: application/json
{
"object": {
"user": {
"name": "John",
"address": {
"city": "NYC",
"zip": "10001"
}
},
"tags": ["admin", "user"]
}
}{
"flattened": {
"user.name": "John",
"user.address.city": "NYC",
"user.address.zip": "10001",
"tags.0": "admin",
"tags.1": "user"
},
"depth": 3,
"keyCount": 5
}Parameters
| Parameter | Type | Description |
|---|---|---|
object |
object | The nested JSON object to flatten |
delimiter |
string | Separator for keys (default: ".") |
maxDepth |
integer | Maximum nesting depth to flatten (default: unlimited) |
safe |
boolean | Preserve arrays as values instead of flattening (default: false) |
Code Examples
JavaScript / Node.js
// Flatten nested JSON
const response = await fetch(
'https://api.tinyfn.io/v1/json/flatten',
{
method: 'POST',
headers: {
'X-API-Key': 'your-api-key',
'Content-Type': 'application/json'
},
body: JSON.stringify({
object: {
user: { name: 'John', address: { city: 'NYC' } }
}
})
}
);
const { flattened } = await response.json();
console.log(flattened);
// { 'user.name': 'John', 'user.address.city': 'NYC' }
// Unflatten back to nested
const unflattenResponse = await fetch(
'https://api.tinyfn.io/v1/json/unflatten',
{
method: 'POST',
headers: {
'X-API-Key': 'your-api-key',
'Content-Type': 'application/json'
},
body: JSON.stringify({ object: flattened })
}
);
const { unflattened } = await unflattenResponse.json();
console.log(unflattened);
// { user: { name: 'John', address: { city: 'NYC' } } }Python
import requests
# Flatten nested JSON
response = requests.post(
'https://api.tinyfn.io/v1/json/flatten',
json={
'object': {
'user': {'name': 'John', 'address': {'city': 'NYC'}}
}
},
headers={'X-API-Key': 'your-api-key'}
)
flattened = response.json()['flattened']
print(flattened)
# {'user.name': 'John', 'user.address.city': 'NYC'}
# Unflatten
response = requests.post(
'https://api.tinyfn.io/v1/json/unflatten',
json={'object': flattened},
headers={'X-API-Key': 'your-api-key'}
)
print(response.json()['unflattened'])cURL
# Flatten JSON
curl -X POST "https://api.tinyfn.io/v1/json/flatten" \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"object": {
"user": {"name": "John", "address": {"city": "NYC"}}
}
}'Common Use Cases
- CSV Export: Flatten JSON to single-row CSV format
- Search Indexing: Create flat documents for full-text search
- Form Data: Convert nested objects for form submissions
- Database Storage: Store in key-value or document stores
- Analytics: Prepare data for analytics platforms
Best Practices
- Choose delimiter carefully: Avoid characters that appear in your keys
- Limit depth: Very deep objects may create unwieldy keys
- Consider arrays: Decide whether to flatten or preserve arrays
- Roundtrip test: Ensure unflatten(flatten(obj)) === obj
Use via MCP
Your AI agent can call this tool directly via Model Context Protocol — no HTTP code needed. Add TinyFn to Claude Desktop, Cursor, or any MCP client:
{
"mcpServers": {
"tinyfn-json": {
"url": "https://api.tinyfn.io/mcp/json/",
"headers": {
"X-API-Key": "your-api-key"
}
}
}
}See all json tools available via MCP in our JSON MCP Tools for AI Agents guide.
Try the JSON Flatten API
Get your free API key and start flattening JSON in seconds.
Get Free API Key