Convert the object to a JSON string.
Note NaN’s and None will be converted to null and datetime objects will be converted to UNIX timestamps.
Parameterspath_or_bufstr, path object, file-like object, or None, default NoneString, path object [implementing os.PathLike[str]], or file-like object implementing a write[] function. If None, the result is returned as a string.
orientstrIndication 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 like
orient='records'
.
Type of date conversion. ‘epoch’ = epoch milliseconds, ‘iso’ = ISO8601. The default depends on the orient. For orient='table'
, the default is ‘iso’. For all other orients, the default is ‘epoch’.
The number of decimal places to use when encoding floating point values.
force_asciibool, default TrueForce encoded string to be ASCII.
date_unitstr, default ‘ms’ [milliseconds]The time unit to encode to, governs timestamp and ISO8601 precision. One of ‘s’, ‘ms’, ‘us’, ‘ns’ for second, millisecond, microsecond, and nanosecond respectively.
default_handlercallable, default NoneHandler to call if object cannot otherwise be converted to a suitable format for JSON. Should receive a single argument which is the object to convert and return a serialisable object.
linesbool, default FalseIf ‘orient’ is ‘records’ write out line-delimited json format. Will throw ValueError if incorrect ‘orient’ since others are not list-like.
compressionstr or dict, default ‘infer’For on-the-fly compression of the output data. If ‘infer’ and ‘path_or_buf’ is
path-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 to None
for no compression. Can also be a dict with key 'method'
set to one of {'zip'
, 'gzip'
, 'bz2'
, 'zstd'
, 'tar'
} and other key-value pairs are forwarded to zipfile.ZipFile
, gzip.GzipFile
, bz2.BZ2File
, zstandard.ZstdCompressor
or tarfile.TarFile
, respectively. As an example, the following could be passed for faster compression and to
create a reproducible gzip archive: compression={'method': 'gzip', 'compresslevel': 1, 'mtime': 1}
.
New in version 1.5.0: Added support for .tar files.
Changed in version 1.4.0: Zstandard support.
indexbool, default TrueWhether to include the index values in the JSON string. Not including the index [index=False
] is only supported when orient is ‘split’ or ‘table’.
Length of whitespace used to indent each record.
New in version 1.0.0.
storage_optionsdict, optionalExtra options that make sense for a particular storage connection, e.g. host, port, username, password, etc. For HTTP[S] URLs the key-value pairs are forwarded to urllib.request.Request
as header options. For other URLs [e.g. starting with “s3://”, and “gcs://”] the key-value pairs are forwarded to fsspec.open
.
Please see fsspec
and urllib
for more details, and for more examples on storage options refer here.
New in version 1.2.0.
ReturnsNone or strIf path_or_buf is None, returns the resulting json format as a string. Otherwise returns None.
See also
read_json
Convert a JSON string to pandas object.
Notes
The behavior of indent=0
varies from the stdlib, which does not indent the output but does insert newlines. Currently, indent=0
and the default indent=None
are equivalent in pandas, though this may change in a future release.
orient='table'
contains a ‘pandas_version’
field under ‘schema’. This stores the version of pandas used in the latest revision of the schema.
Examples
>>> import json >>> df = pd.DataFrame[ ... [["a", "b"], ["c", "d"]], ... index=["row 1", "row 2"], ... columns=["col 1", "col 2"], ... ]
>>> result = df.to_json[orient="split"] >>> parsed = json.loads[result] >>> json.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 = json.loads[result] >>> json.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 = json.loads[result] >>> json.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 = json.loads[result] >>> json.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 = json.loads[result] >>> json.dumps[parsed, indent=4] [ [ "a", "b" ], [ "c", "d" ] ]
Encoding with Table Schema:
>>> result = df.to_json[orient="table"] >>> parsed = json.loads[result] >>> json.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" } ] }