pandas.DataFrame.to_json#

DataFrame.to_json(path_or_buf=None,*,orient=None,date_format=None,double_precision=10,force_ascii=True,date_unit='ms',default_handler=None,lines=False,compression='infer',index=None,indent=None,storage_options=None,mode='w')[source]#

Convert the object to a JSON string.

Note NaN’s and None will be converted to null and datetime objectswill be converted to UNIX timestamps.

Parameters:

path_or_bufstr, path object, file-like object, or None, default None

String, path object (implementing os.PathLike[str]), or file-likeobject implementing a write() function. If None, the result isreturned as a string.

orientstr

Indication of expected JSON string format.

• Series:

  • default is ‘index’

  • allowed values are: {‘split’, ‘records’, ‘index’, ‘table’}.

• DataFrame:

  • default is ‘columns’

  • allowed values are: {‘split’, ‘records’, ‘index’, ‘columns’,‘values’, ‘table’}.

• The format of the JSON string:

  • ‘split’ : dict like {‘index’ -> [index], ‘columns’ -> [columns],‘data’ -> [values]}

  • ‘records’ : list like [{column -> value}, … , {column -> value}]

  • ‘index’ : dict like {index -> {column -> value}}

  • ‘columns’ : dict like {column -> {index -> value}}

  • ‘values’ : just the values array

  • ‘table’ : dict like {‘schema’: {schema}, ‘data’: {data}}

  Describing the data, where data component is likeorient='records'.

date_format{None, ‘epoch’, ‘iso’}

Type of date conversion. ‘epoch’ = epoch milliseconds,‘iso’ = ISO8601. The default depends on theorient. Fororient='table', the default is ‘iso’. For all other orients,the default is ‘epoch’.

double_precisionint, default 10

The number of decimal places to use when encodingfloating point values. The possible maximal value is 15.Passing double_precision greater than 15 will raise a ValueError.

force_asciibool, default True

Force encoded string to be ASCII.

date_unitstr, default ‘ms’ (milliseconds)

The time unit to encode to, governs timestamp and ISO8601precision. One of ‘s’, ‘ms’, ‘us’, ‘ns’ for second, millisecond,microsecond, and nanosecond respectively.

default_handlercallable, default None

Handler to call if object cannot otherwise be converted to asuitable format for JSON. Should receive a single argument which isthe object to convert and return a serialisable object.

linesbool, default False

If ‘orient’ is ‘records’ write out line-delimited json format. Willthrow ValueError if incorrect ‘orient’ since others are notlist-like.

compressionstr or dict, default ‘infer’

For on-the-fly compression of the output data. If ‘infer’ and ‘path_or_buf’ ispath-like, then detect compression from the following extensions: ‘.gz’,‘.bz2’, ‘.zip’, ‘.xz’, ‘.zst’, ‘.tar’, ‘.tar.gz’, ‘.tar.xz’ or ‘.tar.bz2’(otherwise no compression).Set toNone for no compression.Can also be a dict with key'method' setto one of {'zip','gzip','bz2','zstd','xz','tar'} andother key-value pairs are forwarded tozipfile.ZipFile,gzip.GzipFile,bz2.BZ2File,zstandard.ZstdCompressor,lzma.LZMAFile ortarfile.TarFile, respectively.As an example, the following could be passed for faster compression and to createa reproducible gzip archive:compression={'method':'gzip','compresslevel':1,'mtime':1}.

Added in version 1.5.0:Added support for.tar files.

Changed in version 1.4.0:Zstandard support.

indexbool or None, default None

The index is only used when ‘orient’ is ‘split’, ‘index’, ‘column’,or ‘table’. Of these, ‘index’ and ‘column’ do not supportindex=False.

indentint, optional

Length of whitespace used to indent each record.

storage_optionsdict, optional

Extra options that make sense for a particular storage connection, e.g.host, port, username, password, etc. For HTTP(S) URLs the key-value pairsare forwarded tourllib.request.Request as header options. For otherURLs (e.g. starting with “s3://”, and “gcs://”) the key-value pairs areforwarded tofsspec.open. Please seefsspec andurllib for moredetails, and for more examples on storage options referhere.

modestr, default ‘w’ (writing)

Specify the IO mode for output when supplying a path_or_buf.Accepted args are ‘w’ (writing) and ‘a’ (append) only.mode=’a’ is only supported when lines is True and orient is ‘records’.

Returns:

None or str

If path_or_buf is None, returns the resulting json format as astring. Otherwise returns None.

See also

read_json

Convert a JSON string to pandas object.

Notes

The behavior ofindent=0 varies from the stdlib, which does notindent the output but does insert newlines. Currently,indent=0and the defaultindent=None are equivalent in pandas, though thismay change in a future release.

orient='table' contains a ‘pandas_version’ field under ‘schema’.This stores the version ofpandas used in the latest revision of theschema.

Examples

>>>fromjsonimportloads,dumps>>>df=pd.DataFrame(...[["a","b"],["c","d"]],...index=["row 1","row 2"],...columns=["col 1","col 2"],...)

>>>result=df.to_json(orient="split")>>>parsed=loads(result)>>>dumps(parsed,indent=4){    "columns": [        "col 1",        "col 2"    ],    "index": [        "row 1",        "row 2"    ],    "data": [        [            "a",            "b"        ],        [            "c",            "d"        ]    ]}

Encoding/decoding a Dataframe using'records' formatted JSON.Note that index labels are not preserved with this encoding.

>>>result=df.to_json(orient="records")>>>parsed=loads(result)>>>dumps(parsed,indent=4)[    {        "col 1": "a",        "col 2": "b"    },    {        "col 1": "c",        "col 2": "d"    }]

Encoding/decoding a Dataframe using'index' formatted JSON:

>>>result=df.to_json(orient="index")>>>parsed=loads(result)>>>dumps(parsed,indent=4){    "row 1": {        "col 1": "a",        "col 2": "b"    },    "row 2": {        "col 1": "c",        "col 2": "d"    }}

Encoding/decoding a Dataframe using'columns' formatted JSON:

>>>result=df.to_json(orient="columns")>>>parsed=loads(result)>>>dumps(parsed,indent=4){    "col 1": {        "row 1": "a",        "row 2": "c"    },    "col 2": {        "row 1": "b",        "row 2": "d"    }}

Encoding/decoding a Dataframe using'values' formatted JSON:

>>>result=df.to_json(orient="values")>>>parsed=loads(result)>>>dumps(parsed,indent=4)[    [        "a",        "b"    ],    [        "c",        "d"    ]]

Encoding with Table Schema:

>>>result=df.to_json(orient="table")>>>parsed=loads(result)>>>dumps(parsed,indent=4){    "schema": {        "fields": [            {                "name": "index",                "type": "string"            },            {                "name": "col 1",                "type": "string"            },            {                "name": "col 2",                "type": "string"            }        ],        "primaryKey": [            "index"        ],        "pandas_version": "1.4.0"    },    "data": [        {            "index": "row 1",            "col 1": "a",            "col 2": "b"        },        {            "index": "row 2",            "col 1": "c",            "col 2": "d"        }    ]}