read_json() expects the JSON to represent tabular-ish data and uses the orient parameter to interpret its specific structure: 'records', a list of objects, each becoming one row, is one of the most common shapes, while 'columns', a dict mapping column names to dicts of index-value pairs, is another. JSON that's more deeply nested or irregularly structured than a simple table often needs preprocessing, or the separate pd.json_normalize() function, to flatten nested objects into proper DataFrame columns before or instead of a direct read_json() call.
1Understanding pd.read_json()
read_json() expects the JSON to represent tabular-ish data and uses the orient parameter to interpret its specific structure: 'records', a list of objects, each becoming one row, is one of the most common shapes, while 'columns', a dict mapping column names to dicts of index-value pairs, is another. JSON that's more deeply nested or irregularly structured than a simple table often needs preprocessing, or the separate pd.json_normalize() function, to flatten nested objects into proper DataFrame columns before or instead of a direct read_json() call.
For JSON with nested objects or arrays inside each record, reach for pd.json_normalize() instead of, or in addition to, read_json() — it specifically flattens nested structures into flat columns, which plain read_json() doesn't attempt to do automatically.
import pandas as pd
json_text = '[{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}]'
df = pd.read_json(json_text)
print(df)2Practical Example
Here is a real-world application of pd.read_json() showing how it is used in production Pandas code.
import pandas as pd
data = [{"user": "alice", "address": {"city": "NYC", "zip": "10001"}}]
df = pd.json_normalize(data)
print(df.columns.tolist())3Best Practices
Follow these guidelines when working with pd.read_json():
1. Match the orient parameter to your JSON's actual shape, 'records' for a list of objects, which is the most common API response format, instead of relying on default detection
2. Use pd.json_normalize() for JSON with nested objects/arrays that need flattening into columns, rather than fighting read_json()'s simpler tabular assumptions
3. Validate the resulting DataFrame's shape and dtypes after reading, since inconsistent JSON records, missing keys, mixed types, can produce unexpected NaN values or object dtypes
Tip: For JSON with nested objects or arrays inside each record, reach for pd.json_normalize() instead of, or in addition to, read_json() — it specifically flattens nested structures into flat columns, which plain read_json() doesn't attempt to do automatically.
import pandas as pd
json_text = '[{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}]'
df = pd.read_json(json_text)
print(df)