Función Pandas df.to_json()

to_json()Es un método de DataFrame que se utiliza para exportar datos al formato JSON (JavaScript Object Notation).

JSON es el formato estándar para el intercambio de datos en aplicaciones web y API,to_json()Admite la salida en múltiples formatos JSON, incluidos el formato de registros, el formato de índice, el formato de columnas, etc. Puede convertir un pandas DataFrame en una cadena JSON o escribirlo en un archivo, lo que facilita el intercambio de datos con otros sistemas.

Sintaxis básica y parámetros

Formato de sintaxis

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, ...)

Descripción de parámetros

Parámetro	Tipo	Descripción	Valor predeterminado
path_or_buf	str, path object, file-like object	Ruta del archivo; si es None, devuelve una cadena	None
orient	str	Formato JSON: 'split', 'records', 'index', 'columns', 'values', 'table'	None
date_format	str	Formato de fecha: 'epoch', 'iso'	None
double_precision	int	Precisión de punto flotante	10
force_ascii	bool	Si se fuerza la codificación ASCII	True
date_unit	str	Unidad de fecha: 's', 'ms', 'us', 'ns'	'ms'
lines	bool	Formato JSON Lines, un objeto JSON por línea	False
index	bool	Si se incluye el índice	False

Valor de retorno

Tipo de retorno：Noneostr
Cuando se especifica una ruta de archivo, escribe en el archivo y devuelve None.
Cuandopath_or_buf=NoneEn caso contrario, devuelve una cadena en formato JSON.

Ejemplos

A través de los siguientes ejemplos, domina completamenteto_json()sus diversos usos.

Ejemplo 1: Uso básico - Exportar a cadena JSON

Primero crea un DataFrame y luego usato_json()para exportarlo al formato JSON.

Ejemplo

import pandas as pd

# Crear un DataFrame de ejemplo
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)

# Ejemplo 1a: la exportación más básica (sin especificar ruta, devuelve una cadena)
# Por defecto orient='columns'
json_string = df.to_json()
print("Formato JSON predeterminado (columns):")
print(json_string)
print()

# Ejemplo 1b: Exportar a archivo
df.to_json('output_basic.json', orient='records', indent=2)
print("Exportado a output_basic.json")

# Verificación de lectura
df_check = pd.read_json('output_basic.json', orient='records')
print(nVerificar la lectura:)
print(df_check)

Resultado esperado:

默认 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}
]

Análisis del código:

to_json()Si no se especifica la ruta, devuelve una cadena JSON.
Por defectoorient='columns', un objeto JSON por columna.
indent=2Hace que la salida sea más legible (formateada).

Ejemplo 2: Diferentes formatos JSON

Los datos JSON tienen varios formatos,to_json()admite múltiples formatos de salida para satisfacer diferentes necesidades.

Ejemplo

import pandas as pd

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

# Ejemplo 2a: formato records - formato de matriz, un objeto por fila
# El más común, adecuado para la mayoría de las API
json_records = df.to_json(orient='records')
print("Formato Records (un objeto por línea):")
print(json_records)
print()

# Ejemplo 2b: formato index - con índice como clave
json_index = df.to_json(orient='index')
print(Formato Index (con el índice como clave):)
print(json_index)
print()

# Ejemplo 2c: formato columns - con los nombres de las columnas como claves (predeterminado)
json_columns = df.to_json(orient='columns')
print("Formato Columns (con los nombres de columnas como claves):")
print(json_columns)
print()

# Ejemplo 2d: formato split - estructura separada
json_split = df.to_json(orient='split')
print("Formato Split (estructura separada):")
print(json_split)
print()

# Ejemplo 2e: formato values - solo contiene el array de valores
json_values = df.to_json(orient='values')
print(Formato Values (solo contiene valores):)
print(json_values)

Resultado esperado:

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"]]

Análisis del código:

orient='records': Formato de arreglo, cada fila es un objeto JSON, el más utilizado.
orient='index': Usa el índice del DataFrame como clave de nivel superior.
orient='columns': Usa los nombres de columnas como claves, formato predeterminado.
orient='split': Estructura separada, fácil de analizar para los programas.
orient='values': Arreglo de solo valores, sin nombres de columnas ni índice.

Ejemplo 3: Manejo de fechas y codificación de chino

Al exportar JSON, es necesario manejar correctamente las fechas y la codificación de chino.

Ejemplo

import pandas as pd
from datetime import datetime

# Ejemplo 3a: Manejo de campos de fecha
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)]
})

# El formato de fecha predeterminado es una marca de tiempo (milisegundos)
json_timestamp = df_date.to_json(date_format='epoch', orient='records')
print("Formato de fecha - Marca de tiempo:")
print(json_timestamp)
print()

# Fecha en formato ISO
json_iso = df_date.to_json(date_format='iso', orient='records')
print("Formato de fecha - ISO:")
print(json_iso)
print()

# Ejemplo 3b: Procesamiento de chino
df_cn = pd.DataFrame({
'Nombre': ['Zhang San', 'Li Si', 'Wang Wu'],
'Edad': [28, 35, 42],
'Ciudad': ['Pekín', Shanghái, 'Guangzhou']
})

# force_ascii=False permite caracteres no ASCII
json_cn = df_cn.to_json(orient='records', force_ascii=False)
print(Contenido en chino (force_ascii=False):)
print(json_cn)

# Escribir en el archivo (soporta chino por defecto)
df_cn.to_json('output_cn.json', orient='records', force_ascii=False)
print("n exportado a output_cn.json")

# Verificación de lectura
df_cn_check = pd.read_json('output_cn.json')
print(Verificación de lectura:)
print(df_cn_check)

Resultado esperado:

日期格式 - 时间戳:
[{"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    广州
</对>

Análisis del código:

date_format='epoch'Convierte las fechas a marcas de tiempo (milisegundos).
date_format='iso'Convierte las fechas al formato ISO 8601.
force_ascii=FalsePermite conservar los caracteres chinos en JSON en lugar de escaparlos como Unicode.

Ejemplo 4: Formato JSON Lines

JSON Lines es un formato en el que cada línea es un objeto JSON, utilizado a menudo en registros (logs) y procesamiento de grandes datos.

Ejemplo

import pandas as pd

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

# Ejemplo 4a: Formato JSON Lines (un objeto JSON por línea)
# lines=True habilita el formato JSON Lines
json_lines = df.to_json(orient='records', lines=True)
print("Formato JSON Lines:")
print(json_lines)
print()

# Escribir archivo
df.to_json('output_lines.json', orient='records', lines=True)
print("Exportado a output_lines.json")

# Ejemplo 4b: leer el formato JSON Lines
# Debe leerse línea por línea
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("nLeer JSON Lines:")
print(df_from_lines)

Resultado esperado:

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

Análisis del código:

lines=TrueActiva el formato JSON Lines, un objeto JSON por línea.
JSON Lines es adecuado para el procesamiento en flujo y escenarios de grandes datos.
Al leer, es necesario analizar línea por línea y convertirlo a DataFrame.

Notas

Por defectoorient='columns', generalmente se recomienda usarorient='records'un formato más universal.
El uso deforce_ascii=Falsepuede conservar los caracteres chinos.
El formato JSON Lines requiere ser usadoorient='records'en conjunto.
read_json()Al leer, es necesario usar los mismosorientparámetros.
Se recomienda usar el formato de fechadate_format='iso', que es más legible.

Resumen

to_json()Es el método central para exportar un DataFrame al formato JSON. Admite múltiples formatos JSON y puede satisfacer las necesidades de diferentes escenarios, como API web e intercambio de datos.

En el trabajo real, JSON es el formato de datos más utilizado en las aplicaciones web,to_json()combinado conread_json()se puede lograr la importación y exportación de datos. Se recomienda al lector dominar principalmenteorientlos diferentes formatos del parámetro, así comoread_json()su uso combinado.

Pandas 常用函数 Funciones comunes de Pandas

Otras extensiones

Lectura y escritura de datos

Núcleo de procesamiento de datos

Manual de referencia

Estadística y casos

Función Pandas df.to_json()

Sintaxis básica y parámetros

Formato de sintaxis

Descripción de parámetros

Valor de retorno

Ejemplos

Ejemplo 1: Uso básico - Exportar a cadena JSON

Ejemplo

Ejemplo 2: Diferentes formatos JSON

Ejemplo

Ejemplo 3: Manejo de fechas y codificación de chino

Ejemplo

Ejemplo 4: Formato JSON Lines

Ejemplo

Notas

Resumen