现在位置: 首页 > Pandas 教程 > 正文

Pandas df.to_json() 函数

Pandas 常用函数 Pandas 常用函数

to_json() 是 DataFrame 的方法，用于将数据导出为 JSON（JavaScript Object Notation）格式。

JSON 是 Web 应用和 API 数据交换的标准格式，to_json() 支持多种 JSON 格式的输出，包括记录格式、索引格式、列格式等。它能够将 pandas DataFrame 转换为 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, index=False,
                  indent=None, ...)

参数说明

参数类型说明默认值
path_or_bufstr, path object, file-like object文件路径，None 则返回字符串None
orientstrJSON 格式：'split', 'records', 'index', 'columns', 'values', 'table'None
date_formatstr日期格式：'epoch', 'iso'None
double_precisionint浮点数精度10
force_asciibool是否强制 ASCII 编码True
date_unitstr日期单位：'s', 'ms', 'us', 'ns''ms'
linesboolJSON Lines 格式，每行一个 JSON 对象False
indexbool是否包含索引False

返回值

  • 返回类型：None 或 str
  • 当指定文件路径时，写入文件并返回 None。
  • 当 path_or_buf=None 时，返回 JSON 格式的字符串。

实例

通过以下示例，全面掌握 to_json() 的各种用法。

示例 1：基础用法 - 导出为 JSON 字符串

首先创建一个 DataFrame，然后使用 to_json() 导出为 JSON 格式。

实例

import pandas as pd

# 创建一个示例 DataFrame
data = {
    'name': ['Tom', 'Jerry', 'Mike', 'Lucy'],
    'age': [28, 35, 42, 26],
    'city': ['Beijing', 'Shanghai', 'Guangzhou', 'Shenzhen'],
    'salary': [8000, 12000, 15000, 7000]
}
df = pd.DataFrame(data)

# 示例 1a: 最基本的导出（不指定路径，返回字符串）
# 默认 orient='columns'
json_string = df.to_json()
print("默认 JSON 格式 (columns):")
print(json_string)
print()

# 示例 1b: 导出到文件
df.to_json('output_basic.json', orient='records', indent=2)
print("已导出到 output_basic.json")

# 读取验证
df_check = pd.read_json('output_basic.json', orient='records')
print("n验证读取:")
print(df_check)

运行结果预期:

默认 JSON 格式 (columns):
{"name":{"0":"Tom","1":"Jerry","2":"Mike","3":"Lucy"},"age":{"0":28,"1":35,"2":42,"3":26},...}

默认 JSON 格式 (records):
[
  {"name":"Tom","age":28,"city":"Beijing","salary":8000},
  {"name":"Jerry","age":35,"city":"Shanghai","salary":12000},
  {"name":"Mike","age":42,"city":"Guangzhou","salary":15000},
  {"name":"Lucy","age":26,"city":"Shenzhen","salary":7000}
]

代码解析:

  • to_json() 不指定路径时返回 JSON 字符串。
  • 默认 orient='columns'，每列一个 JSON 对象。
  • indent=2 使输出更易读（格式化）。

示例 2：不同的 JSON 格式

JSON 数据有多种格式，to_json() 支持多种输出格式以满足不同需求。

实例

import pandas as pd

# 创建 DataFrame
df = pd.DataFrame({
    'name': ['Tom', 'Jerry', 'Mike', 'Lucy'],
    'age': [28, 35, 42, 26],
    'city': ['Beijing', 'Shanghai', 'Guangzhou', 'Shenzhen']
})

# 示例 2a: records 格式 - 数组格式，每行一个对象
# 最常用，适合大多数 API
json_records = df.to_json(orient='records')
print("Records 格式（每行一个对象）:")
print(json_records)
print()

# 示例 2b: index 格式 - 以索引为键
json_index = df.to_json(orient='index')
print("Index 格式（以索引为键）:")
print(json_index)
print()

# 示例 2c: columns 格式 - 以列名为键（默认）
json_columns = df.to_json(orient='columns')
print("Columns 格式（以列名为键）:")
print(json_columns)
print()

# 示例 2d: split 格式 - 分离结构
json_split = df.to_json(orient='split')
print("Split 格式（分离结构）:")
print(json_split)
print()

# 示例 2e: values 格式 - 只包含值数组
json_values = df.to_json(orient='values')
print("Values 格式（只包含值）:")
print(json_values)

运行结果预期:

Records 格式（每行一个对象）:
[{"name":"Tom","age":28,"city":"Beijing"},
{"name":"Jerry","age":35,"city":"Shanghai"},
{"name":"Mike","age":42,"city":"Guangzhou"},
{"name":"Lucy","age":26,"city":"Shenzhen"}]

Index 格式（以索引为键）:
{"0":{"name":"Tom","age":28,"city":"Beijing"},
"1":{"name":"Jerry","age":35,"city":"Shanghai"},
...}

Columns 格式（以列名为键）:
{"name":{"0":"Tom","1":"Jerry"...},"age":{"0":28...}...}

Split 格式（分离结构）:
{"index":[0,1,2,3],"columns":["name","age","city"],
"data":[["Tom",28,"Beijing"],["Jerry",35,"Shanghai"]...]}

Values 格式（只包含值）:
[["Tom",28,"Beijing"],["Jerry",35,"Shanghai"],["Mike",42,"Guangzhou"],["Lucy",26,"Shenzhen"]]

代码解析:

  • orient='records'：数组格式，每行是一个 JSON 对象，最常用。
  • orient='index'：以 DataFrame 索引作为顶层键。
  • orient='columns'：以列名作为键，默认格式。
  • orient='split'：分离的结构，便于程序解析。
  • orient='values'：纯数值数组，无列名和索引。

示例 3：处理日期和中文编码

JSON 导出时需要正确处理日期和中文编码。

实例

import pandas as pd
from datetime import datetime

# 示例 3a: 处理日期字段
df_date = pd.DataFrame({
    'name': ['Tom', 'Jerry'],
    'birthday': [datetime(1995, 3, 15), datetime(1988, 7, 22)],
    'join_date': [datetime(2020, 1, 10), datetime(2019, 3, 5)]
})

# 默认日期格式是时间戳（毫秒）
json_timestamp = df_date.to_json(date_format='epoch', orient='records')
print("日期格式 - 时间戳:")
print(json_timestamp)
print()

# ISO 格式日期
json_iso = df_date.to_json(date_format='iso', orient='records')
print("日期格式 - ISO:")
print(json_iso)
print()

# 示例 3b: 处理中文
df_cn = pd.DataFrame({
    '姓名': ['张三', '李四', '王五'],
    '年龄': [28, 35, 42],
    '城市': ['北京', '上海', '广州']
})

# force_ascii=False 允许非 ASCII 字符
json_cn = df_cn.to_json(orient='records', force_ascii=False)
print("中文内容（force_ascii=False）:")
print(json_cn)

# 写入文件（默认支持中文）
df_cn.to_json('output_cn.json', orient='records', force_ascii=False)
print("n已导出到 output_cn.json")

# 读取验证
df_cn_check = pd.read_json('output_cn.json')
print("验证读取:")
print(df_cn_check)

运行结果预期:

日期格式 - 时间戳:
[{"name":"Tom","birthday":796...
{"name":"Jerry","birthday":584...}

日期格式 - ISO:
[{"name":"tom","birthday":"1995-03-15T00:00:00.000Z",...}]

中文内容（force_ascii=False）:
[{"姓名":"张三","年龄":28,"城市":"北京"},
{"姓名":"李四","年龄":35,"城市":"上海"},
{"姓名":"王五","年龄":42,"城市":"广州"}]

已导出到 output_cn.json

验证读取:
    姓名   年龄   城市
0  张三   (read_json 的    格式    orient='records' 匹配 to_json 的 orient='records')    北京
1 配对    李四   35    上海
2  王五   42    广州
</对>

代码解析:

  • date_format='epoch' 将日期转为时间戳（毫秒）。
  • date_format='iso' 将日期转为 ISO 8601 格式。
  • force_ascii=False 允许在 JSON 中保留中文字符，而不是转义为 Unicode。

示例 4：JSON Lines 格式

JSON Lines 是每行一个 JSON 对象的格式，常用于日志和大数据处理。

实例

import pandas as pd

# 创建 DataFrame
df = pd.DataFrame({
    'name': ['Tom', 'Jerry', 'Mike', 'Lucy'],
    'age': [28, 35, 42, 26],
    'city': ['Beijing', 'Shanghai', 'Guangzhou', 'Shenzhen']
})

# 示例 4a: JSON Lines 格式（每行一个 JSON 对象）
# lines=True 启用 JSON Lines 格式
json_lines = df.to_json(orient='records', lines=True)
print("JSON Lines 格式:")
print(json_lines)
print()

# 写入文件
df.to_json('output_lines.json', orient='records', lines=True)
print("已导出到 output_lines.json")

# 示例 4b: 读取 JSON Lines 格式
# 需要逐行读取
import json
df_lines_list = []
with open('output_lines.json', 'r', encoding='utf-8') as f:
    for line in f:
        df_lines_list.append(json.loads(line.strip()))

df_from_lines = pd.DataFrame(df_lines_list)
print("n读取 JSON Lines:")
print(df_from_lines)

运行结果预期:

JSON Lines 格式:
{"name":"Tom","age":28,"city":"Beijing"}
{"name":"Jerry","age":35,"city":"Shanghai"}
{"name":"Mike","age":42,"city":"city":"Guangzhou"}
{"name":"Lucy","age":26,"city":"Shenzhen"}

已导出到 output_lines.json

读取 JSON Lines:
    name  age       city
0    Tom   28    Beijing
对    读    Jerry   35    Shanghai
2   Mike   42   格式    Guangzhou
3   Lucy   26    Shenzhen

代码解析:

  • lines=True 启用 JSON Lines 格式，每行一个 JSON 对象。
  • JSON Lines 适合流式处理和大数据场景。
  • 读取时需要逐行解析并转换为 DataFrame。

注意事项

  • 默认 orient='columns'，一般建议使用 orient='records' 更通用。
  • 使用 force_ascii=False 可以保留中文字符。
  • JSON Lines 格式需要配合 orient='records' 使用。
  • read_json() 读取时，需要使用相同的 orient 参数。
  • 日期格式推荐使用 date_format='iso'，更易读。

小结

to_json() 是 DataFrame 导出为 JSON 格式的核心方法。它支持多种 JSON 格式，能够满足 Web API、数据交换等不同场景的需求。

在实际工作中，JSON 是 Web 应用最常用的数据格式，to_json() 配合 read_json() 可以实现数据的导入导出。建议读者重点掌握 orient 参数的不同格式，以及与 read_json() 的配对使用。

Pandas 常用函数 Pandas 常用函数

返回顶部
© 2026 菜鸟教程
备案号：闽ICP备15012807号-1

∧