pandas df.to_json() 转换为 JSON 格式字符串

看过来

《pandas 教程》持续更新中，提供建议、纠错、催更等加作者微信: gr99123（备注：pandas教程）和关注公众号「盖若」ID: gairuo。跟作者学习，请进入 Python学习课程。欢迎关注作者出版的书籍：《深入浅出Pandas》和《Python之光》。

pandas.DataFrame.to_json() 是 Pandas 中用于将 DataFrame 对象转换为 JSON 格式字符串或将其写入 JSON 文件的方法。JSON（JavaScript Object Notation）是一种轻量级的数据交换格式，广泛应用于数据传输和存储。通过 to_json() 方法，可以方便地将数据以 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'
)

参数详解

path_or_buf
- 类型: str、pathlib.Path、file-like object、None
- 默认值: None
- 意义: 指定将 JSON 数据写入的文件路径、URL 或文件对象。如果设置为 None，则返回 JSON 字符串。
orient
- 类型: str，可选
- 默认值: 'columns'
- 意义: 指定 JSON 的格式。常用选项包括：
  - 'split': 分割格式，包含 index、columns 和 data。
  - 'records': 每一行作为一个字典。
  - 'index': 索引为键，值为列数据。
  - 'columns': 列为键，值为列数据。
  - 'values': 仅包含值，不包含索引和列名。
  - 'table': 兼容 JSON Table Schema 的格式。
date_format
- 类型: str，可选
- 默认值: None
- 意义: 指定日期格式。可选值包括：
  - 'epoch': 将日期转换为自1970年1月1日以来的毫秒数。
  - 'iso': 使用 ISO 格式的日期字符串。
  - None: 默认情况下，日期将以毫秒数表示。
double_precision
- 类型: int，可选
- 默认值: 10
- 意义: 指定浮点数的精度（小数点后的位数）。默认保留10位小数。
force_ascii
- 类型: bool，可选
- 默认值: True
- 意义: 如果为 True，所有非 ASCII 字符将被转义。如果为 False，则允许非 ASCII 字符直接出现在输出中。
date_unit
- 类型: str，可选
- 默认值: 'ms'
- 意义: 指定日期时间的单位。可选值包括：
  - 's': 秒
  - 'ms': 毫秒
  - 'us': 微秒
  - 'ns': 纳秒
default_handler
- 类型: callable，可选
- 默认值: None
- 意义: 指定一个自定义的函数，用于处理无法序列化的对象。
lines
- 类型: bool，可选
- 默认值: False
- 意义: 如果为 True，则每一行将作为一个单独的 JSON 对象，适用于大规模数据的流式处理。
compression
- 类型: str，可选
- 默认值: 'infer'
- 意义: 指定文件的压缩格式。可选值包括 'gzip'、'bz2'、'zip'、'xz'、'zstd' 等。'infer' 会根据文件扩展名自动推断。
index
- 类型: bool，可选
- 默认值: True
- 意义: 指定是否在 JSON 中包含索引信息。如果设置为 False，则不包含索引。
indent
- 类型: int，可选
- 默认值: None
- 意义: 指定缩进级别，以美化输出的 JSON 格式。设置为正整数时，将在每个嵌套级别添加相应数量的空格。
storage_options
- 类型: dict，可选
- 默认值: None
- 意义: 指定与文件系统连接的额外选项，如 S3 或 GCS 的认证信息。
mode
- 类型: str，可选
- 默认值: 'w'
- 意义: 指定文件的打开模式，默认为写入模式 'w'。其他选项包括 'a'（追加模式）。

返回值

类型: str 或 None
意义:
- 如果 path_or_buf 为 None，则返回一个包含 JSON 数据的字符串。
- 如果指定了 path_or_buf，则将 JSON 数据写入指定的位置，返回 None。

使用场景

DataFrame.to_json() 主要用于将 DataFrame 数据导出为 JSON 格式，以便与其他系统或应用程序进行数据交换。常见的使用场景包括：

将数据上传到 Web API。
保存配置或结果数据以供后续使用。
与前端应用程序进行数据交互。
备份和存储数据。

示例

示例 1：将 DataFrame 转换为 JSON 字符串

import pandas as pd

# 构造示例数据
data = {
    'Name': ['Alice', 'Bob', 'Charlie'],
    'Age': [30, 25, 35],
    'City': ['New York', 'Los Angeles', 'Chicago']
}
df = pd.DataFrame(data)

# 将 DataFrame 转换为 JSON 字符串
json_str = df.to_json()

print(json_str)

输出

{"Name":{"0":"Alice","1":"Bob","2":"Charlie"},"Age":{"0":30,"1":25,"2":35},"City":{"0":"New York","1":"Los Angeles","2":"Chicago"}}

示例 2：将 DataFrame 写入 JSON 文件

import pandas as pd

# 构造示例数据
data = {
    'Name': ['Alice', 'Bob', 'Charlie'],
    'Age': [30, 25, 35],
    'City': ['New York', 'Los Angeles', 'Chicago']
}
df = pd.DataFrame(data)

# 将 DataFrame 写入 JSON 文件
df.to_json('data.json', orient='records', lines=True, indent=4)

# 读取并打印 JSON 文件内容
with open('data.json', 'r', encoding='utf-8') as file:
    content = file.read()
    print(content)

输出

{
    "Name": "Alice",
    "Age": 30,
    "City": "New York"
}
{
    "Name": "Bob",
    "Age": 25,
    "City": "Los Angeles"
}
{
    "Name": "Charlie",
    "Age": 35,
    "City": "Chicago"
}

示例 3：指定日期格式和浮点数精度

import pandas as pd
from datetime import datetime

# 构造示例数据
data = {
    'Name': ['Alice', 'Bob', 'Charlie'],
    'Birthdate': [datetime(1990, 1, 1), datetime(1985, 5, 23), datetime(1992, 7, 15)],
    'Score': [95.123456789, 88.987654321, 92.456789123]
}
df = pd.DataFrame(data)

# 将 DataFrame 转换为 JSON 字符串，指定日期格式和浮点数精度
json_str = df.to_json(date_format='iso', double_precision=5, indent=4)

print(json_str)

输出

{
    "Name": {
        "0": "Alice",
        "1": "Bob",
        "2": "Charlie"
    },
    "Birthdate": {
        "0": "1990-01-01T00:00:00.000Z",
        "1": "1985-05-23T00:00:00.000Z",
        "2": "1992-07-15T00:00:00.000Z"
    },
    "Score": {
        "0": 95.12346,
        "1": 88.98765,
        "2": 92.45679
    }
}

示例 4：不强制 ASCII 并使用缩进美化 JSON

import pandas as pd

# 构造包含非 ASCII 字符的示例数据
data = {
    '姓名': ['艾丽丝', '鲍勃', '查理'],
    '年龄': [30, 25, 35],
    '城市': ['纽约', '洛杉矶', '芝加哥']
}
df = pd.DataFrame(data)

# 将 DataFrame 转换为 JSON 字符串，不强制 ASCII 并使用缩进
json_str = df.to_json(force_ascii=False, indent=2)

print(json_str)

输出

{
  "姓名": {
    "0": "艾丽丝",
    "1": "鲍勃",
    "2": "查理"
  },
  "年龄": {
    "0": 30,
    "1": 25,
    "2": 35
  },
  "城市": {
    "0": "纽约",
    "1": "洛杉矶",
    "2": "芝加哥"
  }
}

示例 5：逐行写入 JSON 对象（适用于大数据）

import pandas as pd

# 构造示例数据
data = {
    'Name': ['Alice', 'Bob', 'Charlie'],
    'Age': [30, 25, 35],
    'City': ['New York', 'Los Angeles', 'Chicago']
}
df = pd.DataFrame(data)

# 将 DataFrame 逐行写入 JSON 文件
df.to_json('data_lines.json', orient='records', lines=True)

# 读取并打印 JSON 文件内容
with open('data_lines.json', 'r', encoding='utf-8') as file:
    for line in file:
        print(line.strip())

输出

{"Name":"Alice","Age":30,"City":"New York"}
{"Name":"Bob","Age":25,"City":"Los Angeles"}
{"Name":"Charlie","Age":35,"City":"Chicago"}

总结

DataFrame.to_json() 是一个强大的方法，用于将 Pandas DataFrame 转换为多种格式的 JSON 数据。通过灵活配置参数，可以控制 JSON 的格式、日期处理、浮点数精度等，以满足不同的数据交换和存储需求。在数据分析和机器学习项目中，掌握 to_json() 的使用方法，可以有效地实现数据的导出和集成，与其他系统或前端应用程序进行高效的数据交互。

参考

https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_json.html

< to_pickle() 序列化为 pickle 文件 pandas 文件或数据的读取和导出 to_html() 转换为 HTML 表格格式 >

更新时间：2024-10-10 09:11:20 标签：pandas python json