Table Of Contents

Search

Enter search terms or a module, class or function name.

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=None)[source]

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.

Parameters:

path_or_buf : the path or buffer to write the result string

if this is None, return the converted string

orient : string

  • Series

    • default is ‘index’
    • allowed values are: {‘split’,’records’,’index’}

  • DataFrame

    • default is ‘columns’
    • allowed values are: {‘split’,’records’,’index’,’columns’,’values’}

  • 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, and the data component is like orient='records'.

      Changed in version 0.20.0.

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

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’.

double_precision : The number of decimal places to use when encoding

floating point values, default 10.

force_ascii : force encoded string to be ASCII, default True.

date_unit : string, 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_handler : callable, default None

Handler 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.

lines : boolean, default False

If ‘orient’ is ‘records’ write out line delimited json format. Will throw ValueError if incorrect ‘orient’ since others are not list like.

New in version 0.19.0.

compression : {None, ‘gzip’, ‘bz2’, ‘xz’}

A string representing the compression to use in the output file, only used when the first argument is a filename

New in version 0.21.0.
Returns:

same type as input object with filtered info axis

See also

pd.read_json

Examples

>>> df = pd.DataFrame([['a', 'b'], ['c', 'd']],
...                   index=['row 1', 'row 2'],
...                   columns=['col 1', 'col 2'])
>>> df.to_json(orient='split')
'{"columns":["col 1","col 2"],
  "index":["row 1","row 2"],
  "data":[["a","b"],["c","d"]]}'

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

>>> df.to_json(orient='index')
'{"row 1":{"col 1":"a","col 2":"b"},"row 2":{"col 1":"c","col 2":"d"}}'

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

>>> df.to_json(orient='records')
'[{"col 1":"a","col 2":"b"},{"col 1":"c","col 2":"d"}]'

Encoding with Table Schema

>>> df.to_json(orient='table')
'{"schema": {"fields": [{"name": "index", "type": "string"},
                        {"name": "col 1", "type": "string"},
                        {"name": "col 2", "type": "string"}],
             "primaryKey": "index",
             "pandas_version": "0.20.0"},
  "data": [{"index": "row 1", "col 1": "a", "col 2": "b"},
           {"index": "row 2", "col 1": "c", "col 2": "d"}]}'
Scroll To Top