pandas.read_json for JSON Data Handling: Step-by-Step Examples

published on 04 April 2024

Handling JSON data with pandas in Python is a powerful way to explore, clean, and analyze complex datasets. Here's a quick guide to get you started:

  • Why JSON? It's simple, flexible, and widely supported, making it ideal for data storage and communication.
  • Why pandas? It excels at handling table-like data, transforming JSON into easy-to-manipulate DataFrames.
  • Key Functions: Use pd.read_json() to load JSON data into DataFrames and pd.json_normalize() for nested JSON.
  • Customization: Adjust how JSON converts into DataFrames with parameters like orient, and turn DataFrames back into JSON with customization options.
  • Handling Large Files: Techniques like chunksize reading, compression, and using Dask can improve performance.
  • Optimizations: Setting data types, using categoricals, and other tricks can enhance memory usage and speed.

This guide aims to equip you with the knowledge to efficiently manage JSON data with pandas, turning complex datasets into actionable insights.

Understanding JSON Data Format

JSON is a way to store and move data that's easy for both people and computers to work with. Here's a simple look at what JSON is and why it's so handy:

What is JSON?

  • Short for JavaScript Object Notation
  • A simple text format for sharing data
  • Easy to read and write for people, easy to understand for computers
  • Comes from JavaScript but works with many programming languages
  • Organizes data with names and values, and can list items in order
  • Handles basic stuff like numbers, text, true/false values, and empty values
  • You can put objects and lists inside each other

For instance:

  "name": "John",
  "age": 30, 
  "isAdmin": false,
  "hobbies": [

Why is JSON Popular?

People like using JSON for sending data online because:

  • It's simple: The format is straightforward and quick to use
  • It's flexible: You can show complex data and it works with many languages
  • It's small: Takes up less space than other formats like XML
  • It's easy to read: The data looks clean and understandable
  • It's everywhere: All major programming languages and platforms support it

This makes JSON a top pick for web services, API data, settings files, and more.

How JSON Compares to Other Formats

CSV: A format that uses commas to separate values. It's simple but can't show different levels of data. Also, it doesn't specify what type of data each value is.

XML: A more complex format that can show detailed and structured data. However, it's bulkier and harder for humans to handle.

So, while XML can deal with more complicated data, JSON is a good middle ground. It's easier to use and faster than XML.

Why Use JSON with Pandans?

Pandas is a Python library that's great for dealing with JSON:

  • You can load JSON data into a format called DataFrames from files or the internet
  • Pandas lets you tweak, analyze, combine, and change JSON data easily
  • You can also turn your organized data back into JSON if needed

Using JSON with pandas combines the ease of JSON with powerful tools for managing data.

Getting Started with pandas.read_json

The pd.read_json() function is like a magic spell in pandas that helps you pull JSON data into a DataFrame, making it much easier to work with. Let's break down how it works in simple terms:

How It Works

pd.read_json('where your JSON is', options you might want to add)
  • 'where your JSON is': This could be a file on your computer, a web address, or even a piece of JSON text.
  • Options: There are a bunch of settings you can tweak to make sure your JSON data loads just right. For example, you can tell pandas exactly how your JSON is structured, what kind of data to expect, and even how to handle dates.


To load JSON from a file named data.json:

import pandas as pd

df = pd.read_json('data.json')

This command tells pandas to open the data.json file and transform the JSON Data in Python into a DataFrame, which is like a super handy table that pandas can easily work with.

Things to Remember

  • The read_json() function is pretty smart and can figure out a lot on its own, but sometimes you need to give it hints, especially if your JSON data is a bit complicated.
  • For nested data, you can use pd.json_normalize() to make things simpler.
  • You can also load JSON directly from the internet by giving a URL instead of a file name.
  • If your JSON data is in a special format where each line is its own JSON object, make sure to use lines=True.
  • If you're dealing with just one piece of data, pandas will give you a Series instead of a DataFrame.

By starting with pd.read_json(), you're unlocking all the powerful tools pandas offers for data manipulation with pandas, joining dataframes, and more. It's your first step towards making sense of JSON data with pandas.


Step-by-Step Examples

Example 1: Loading a Local JSON File

Let's start with how to get JSON data from a file on your computer into a pandas DataFrame using pd.read_json():

  • First, you need pandas. So, make sure to import it along with JSON:
import pandas as pd
import json
  • Next, open your JSON file and load its contents into something Python can work with, like a dictionary:
with open('data.json') as json_file:
    data = json.load(json_file)
  • Now, you can use pd.read_json() to turn that dictionary into a DataFrame, which is a fancy table pandas can easily handle:
df = pd.read_json(data)
  • Finally, print the first few rows of your DataFrame to check if everything looks good:

This method turns the JSON Data in Python from your file into a DataFrame that's ready for data manipulation with pandas.

Example 2: Loading JSON Data from a URL

To directly load JSON into a DataFrame from a website, do this:

url = ''
df = pd.read_json(url)

Remember, when fetching JSON from the internet:

  • Make sure the URL points directly to the JSON data
  • If the data is protected, you might need to handle login details
  • Set a timeout to avoid waiting forever if something goes wrong
  • Be ready to deal with errors like bad links or connection problems

Example 3: Handling Nested JSON Objects

Dealing with nested JSON, where data is tucked inside other data, can be tricky. But, pd.json_normalize() can help flatten it out:

from import json_normalize

nested_df = json_normalize(data, record_path=['info', 'results'], 
                            meta=['id', 'type'])

This command stretches out the nested parts into their own columns while keeping the main info.

Some tips for nested JSON:

  • Point record_path to where the nested data is
  • Use meta to keep important info alongside
  • Set errors to 'ignore' if some nested data might be missing
  • You might need to repeat this for different layers of nesting

Example 4: Customizing DataFrame with orient Parameter

The orient option lets you change how JSON turns into a DataFrame:

df = pd.read_json(data, orient='columns')
  • split: Turns indexed rows and columns from nested keys (this is the usual way)
  • columns: Uses columns indexed with row data from nested values
  • index: Uses JSON keys as indexes with data in columns

Choose orient based on your DataFrame's needed structure.

Example 5: Converting DataFrame back to JSON

When you're done cleaning and analyzing, you might want to save your DataFrame as JSON again. Here's how:


And if you want to customize the output:

cleaned_df.to_json('cleaned_data.json', orient='records', date_format='iso')

This lets you adjust the format and how dates look in your final JSON.

Advanced Tips and Tricks

Here are some advanced tips to help you work better with pd.read_json() and handle JSON data in pandas:

Improve Load Speed with Chunksize

If you're dealing with really big JSON files, you can read the data in smaller pieces instead of all at once:

for df in pd.read_json('big_data.json', lines=True, chunksize=1000):
    # Do something with each piece

This way, you read the file in parts of 1000 lines each, which helps avoid running out of memory.

Use Compression for Faster Transfers

When getting JSON from the internet, turning on GZIP compression can make things download faster:

df = pd.read_json('', compression='gzip')

Explicitly Set Data Types

Pandas guesses the type of data when reading JSON, but you can tell it exactly what to expect to use memory better:

dtypes = {'id': 'int64', 'text': 'string'}  
df = pd.read_json('data.json', dtype=dtypes)

Improve Load Performance with Dask

For really big datasets, you can use Dask to spread out the work across multiple computer cores:

import dask.dataframe as dd
df = dd.read_json('giant_data.json') 

This makes pandas faster by doing several things at once.

Use Categoricals to Save Memory

Change columns with lots of repeating values to 'category' type:

df['category'] = df['category'].astype('category')  

This helps save memory when you have many repeating values.

By using these tips, you can manage even very large and complex JSON datasets efficiently with pandas. These optimizations can really help pd.read_json() work better.


In this guide, we've shown how pandas makes it easy to handle JSON data in Python. Here's what we've covered:

  • JSON is a handy way to store data because it's simple, flexible, and works well across different platforms. When we use it with pandas, we get to combine these benefits with powerful tools for analyzing data.
  • The pd.read_json() function lets us quickly turn JSON into pandas DataFrames, whether that JSON comes from files or the internet. This opens the door to all sorts of data manipulation with pandas.
  • If your JSON is complicated and nested, pd.json_normalize() can help straighten it out so it's easier to deal with.
  • You have options to tweak how JSON is turned into DataFrames and to turn your data back into JSON when you're done.
  • For big JSON files, tricks like reading in chunks and using compression can make things run smoother.

With these tools from pandas, handling complex JSON data becomes much simpler. You can do things like explore your data, make charts, or even use it for machine learning projects. We suggest grabbing some JSON data and trying out what you've learned. With pandas, working with JSON data in Python becomes a lot more doable and fun.

Related posts

Read more