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 theto_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

Theto_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 withorient='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 theto_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 filedf.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 namedoutput_json_file.json in your working directory.

Control JSON Structure with Orient Parameter

Theorient parameter in theto_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 theto_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 JSONprint("Column-oriented JSON")print(df.to_json(orient="columns"))# Record-oriented JSONprint("\nRecord-oriented JSON")print(df.to_json(orient="records"))# Split-oriented JSONprint("\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 thedate_format anddate_unit parameters.

Example

The following example demonstrates how to handle dates while converting Pandas DataFrame to JSON using thedate_format anddate_unit parameters of theto_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 formatprint('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

Theindent parameter in theto_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 Theindent parameter of theto_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 Indentationresult = df.to_json(indent=5)# Print the resulting JSON stringprint("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 themode option of theto_json() method. This option is supported only when thelines parameter is set toTrue andorient is set to'records'.

Example

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

import pandas as pd# Create a DataFramedf = 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 DataFrameresult = pd.read_json('output.json', lines=True)print('DataFrame from JSON File:')print(result)# Additional datadf2 = pd.DataFrame({    "Name": ['Vinay'],    "Gender": ['Male'],    "Age": [40]})# Append to the existing JSON filedf2.to_json("output.json", orient="records", lines=True, mode="a")# Read the JSON data back into a DataFrameresult_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