Python Pandas - Write JSON

---

---

The Pandas library in Python provides a simple and efficient way to convert Series and DataFrames into JSON strings or write them to JSON files using the to_json() method.

JSON stands for JavaScript Object Notation and is a lightweight, text-based format used for structured data exchange and storage. In this tutorial, we will explore the various advanced options available for exporting data to JSON format using Pandas.

The to_json() Method

The to_json() method allows exporting Pandas objects (Series or DataFrame) into JSON strings or files with more formatting options.

The syntax of this method is as follows −

object.to_json(path_or_buf=None, *, orient=None, date_format=None, lines=False, compression='infer', mode='w')

Below are the key parameters of the method −

• path_or_buf: Specifies the file path or buffer where the JSON output will be written. If set to None, the method returns a JSON string.

• orient: Specifies the format of the JSON string.

• date_format: Specifies the format for encoding dates.

• lines: If set to True with orient='records', writes each record on a new line.

• mode: Specifies the file mode when writing to a file. Available options are 'w' (write), and 'a' (append).

Example

Let's convert a Pandas DataFrame into a JSON string using the to_json() method.

import pandas as pd

# Create a DataFrame 
df = pd.DataFrame({"Name":["Kiran", "Dev", "Priya"], 
"Gender": ["Male", "Female", "Female"],
"Age": [21, 25, 29]})

# Write DataFrame to a JSON file
df.to_json("output_json_file.json")

print("The output JSON file has been written successfully.")

On executing the above code we will get the following output −

The output JSON file has been written successfully.

After executing the above code, you can find the created JSON file named output_json_file.json in your working directory.

Control JSON Structure with Orient Parameter

The orient parameter in the to_json() method controls the structure of the JSON output. The main options include "split", "records", "index", "columns", "values", and "table". Each option determines how the JSON output is structured −

• split: Splits data into columns, index, and data sections.

• records: Each row is represented as a dictionary.

• index: Keys are index, values are dictionaries.

• columns: Keys are column names, values are dictionaries.

• table: The JSON Table Schema.

Example

The following example demonstrates the use of the to_json() method with the different orientation options.

import pandas as pd

# Create a DataFrame 
df = pd.DataFrame({"Name":["Kiran", "Dev", "Priya"], 
"Gender": ["Male", "Female", "Female"],
"Age": [21, 25, 29]})

# Column-oriented JSON
print("Column-oriented JSON")
print(df.to_json(orient="columns"))

# Record-oriented JSON
print("\nRecord-oriented JSON")
print(df.to_json(orient="records"))

# Split-oriented JSON
print("\nSplit-oriented JSON")
print(df.to_json(orient="split"))

Following is an output of the above code −

Column-oriented JSON
{"Name":{"0":"Kiran","1":"Dev","2":"Priya"},"Gender":{"0":"Male","1":"Female","2":"Female"},"Age":{"0":21,"1":25,"2":29}}

Record-oriented JSON
[{"Name":"Kiran","Gender":"Male","Age":21},{"Name":"Dev","Gender":"Female","Age":25},{"Name":"Priya","Gender":"Female","Age":29}]

Split-oriented JSON
{"columns":["Name","Gender","Age"],"index":[0,1,2],"data":[["Kiran","Male",21],["Dev","Female",25],["Priya","Female",29]]}

Handling Dates While Converting DataFrame to JSON

Pandas can serialize datetime objects into JSON with specific formats using the date_format and date_unit parameters.

Example

The following example demonstrates how to handle dates while converting Pandas DataFrame to JSON using the date_format and date_unit parameters of the to_json() method.

import pandas as pd

# Create a DataFrame 
df = pd.DataFrame({
    "A": [1, 2, 3],
    "date": pd.date_range("2025-01-01", periods=3)
})

# Writing ISO format
print('Output JSON with dates converted to ISO format:')
print(df.to_json(date_format="iso"))

# Writing Epoch format (milliseconds)
print('\nOutput JSON with dates converted to Epoch format (milliseconds):')
print(df.to_json(date_format="epoch", date_unit="ms"))

Upon executing the above code, we obtain the following output −

Output JSON with dates converted to ISO format:
{"A":{"0":1,"1":2,"2":3},"date":{"0":"2025-01-01T00:00:00.000","1":"2025-01-02T00:00:00.000","2":"2025-01-03T00:00:00.000"}}

Output JSON with dates converted to Epoch format (milliseconds):
{"A":{"0":1,"1":2,"2":3},"date":{"0":1735689600000,"1":1735776000000,"2":1735862400000}}

Exporting DataFrame to JSON with Custom Indentation

The indent parameter in the to_json() method controls the amount of white-space used to format JSON output

Example

The following example demonstrates how to specify the custom indentation for the output JSON by using the The indent parameter of the to_json() method.

import pandas as pd

# Create a DataFrame 
df = pd.DataFrame({"Name":["Kiran", "Dev", "Priya"], 
"Gender": ["Male", "Female", "Female"],
"Age": [21, 25, 29]})

# Convert to JSON with Custom Indentation
result = df.to_json(indent=5)

# Print the resulting JSON string
print("Output JSON String:")
print(result)

When we run above program, it produces following result −

Output JSON String:
{
     "Name":{
          "0":"Kiran",
          "1":"Dev",
          "2":"Priya"
     },
     "Gender":{
          "0":"Male",
          "1":"Female",
          "2":"Female"
     },
     "Age":{
          "0":21,
          "1":25,
          "2":29
     }
}

Pandas Appending to Existing JSON File

Pandas also supports exporting Pandas object to an existing JSON file using the mode option of the to_json() method. This option is supported only when the lines parameter is set to True and orient is set to 'records'.

Example

The following example demonstrates how to append data to an existing JSON file.

import pandas as pd

# Create a DataFrame
df = pd.DataFrame({
    "Name": ["Kiran", "Dev", "Priya"], 
    "Gender": ["Male", "Female", "Female"],
    "Age": [21, 25, 29]
})

# Convert to JSON with lines=True and orient="records"
df.to_json("output.json", orient="records", lines=True)

# Read the JSON data back into a DataFrame
result = pd.read_json('output.json', lines=True)
print('DataFrame from JSON File:')
print(result)

# Additional data
df2 = pd.DataFrame({
    "Name": ['Vinay'],
    "Gender": ['Male'],
    "Age": [40]
})

# Append to the existing JSON file
df2.to_json("output.json", orient="records", lines=True, mode="a")

# Read the JSON data back into a DataFrame
result_2 = pd.read_json('output.json', lines=True)
print('\nDataFrame from JSON File after Appending:')
print(result_2)

Following is an output of the above code −

DataFrame from JSON File:

	Name	Gender	Age
0	Kiran	Male	21
1	Dev	Female	25
2	Priya	Female	29

DataFrame from JSON File after Appending:

	Name	Gender	Age
0	Kiran	Male	21
1	Dev	Female	25
2	Priya	Female	29
3	Vinay	Male	40