本文详解如何正确解析 api 返回的 json 响应，并将其结构化为 pandas dataframe，重点解决因编码、json 解析或数据嵌套导致的空表、nameerror: name 'null' is not defined 等常见错误。
本文详解如何正确解析 api 返回的 json 响应，并将其结构化为 pandas dataframe，重点解决因编码、json 解析或数据嵌套导致的空表、nameerror: name 'null' is not defined 等常见错误。
在使用 Python 调用 RESTful API（如 WTO 时间序列接口）时，开发者常遇到“成功获取响应却无法转成 DataFrame”的问题。根本原因在于：原始响应是字节流（bytes），需先解码为字符串，再经 json.loads() 解析为 Python 对象（如 list 或 dict），最后才能被 pd.DataFrame() 正确识别。直接对 response.read().decode('ASCII') 的结果调用 pd.DataFrame() 会传入一个字符串，而非结构化数据，因此生成空 DataFrame；而用 eval() 尝试解析则会失败——因为 JSON 中的 null 不是 Python 的 None，eval() 无法识别，抛出 NameError。
以下是推荐的完整处理流程（含健壮性增强）：
✅ 正确步骤与示例代码
import urllib.request
import json
import pandas as pd
url = "https://api.wto.org/timeseries/v1/indicator_categories?lang=1"
headers = {
'Cache-Control': 'no-cache',
'Ocp-Apim-Subscription-Key': '21cda66d75fc4010b8b4d889f4af6ccd',
}
# 1. 发起请求（推荐使用 with 语句确保连接关闭）
req = urllib.request.Request(url, headers=headers)
try:
with urllib.request.urlopen(req) as response:
if response.getcode() != 200:
raise Exception(f"HTTP {response.getcode()}: 请求失败")
raw_data = response.read()
# 2. 解码 + 解析 JSON（优先用 utf-8，兼容性优于 ASCII）
decoded = raw_data.decode('utf-8')
json_obj = json.loads(decoded) # ✅ 关键：将 JSON 字符串转为 Python 原生对象
# 3. 智能判断数据结构并构造 DataFrame
if isinstance(json_obj, list):
# 直接是字典列表 → 可直接构建 DataFrame
df = pd.DataFrame(json_obj)
elif isinstance(json_obj, dict):
# 是字典 → 查找实际数据所在的键（常见如 'results', 'data', 'items'）
# 先打印顶层键供调试
print("JSON 根级键:", list(json_obj.keys()))
# 示例：假设数据在 'categories' 键下
if 'categories' in json_obj:
df = pd.DataFrame(json_obj['categories'])
else:
# 尝试通用 fallback：提取所有值中第一个 list 类型子项
nested_lists = [v for v in json_obj.values() if isinstance(v, list)]
if nested_lists:
df = pd.DataFrame(nested_lists[0])
else:
raise ValueError("未在 JSON 字典中找到可转换的列表数据")
else:
raise TypeError(f"不支持的 JSON 根类型: {type(json_obj).__name__}")
print(f"✅ 成功创建 DataFrame，形状: {df.shape}")
print(df.head())
except json.JSONDecodeError as e:
print(f"❌ JSON 解析失败: {e}")
except UnicodeDecodeError:
print("❌ 解码失败：尝试更换编码（如 'latin-1'）")
except Exception as e:
print(f"❌ 其他错误: {e}")⚠️ 关键注意事项
- 永远避免 eval() 解析 JSON：eval() 存在严重安全风险（可执行任意代码），且不兼容 JSON 规范（如 null/true/false）；务必使用 json.loads()。
- 编码选择：API 响应通常为 UTF-8，decode('utf-8') 比 'ASCII' 更可靠；若遇乱码，可尝试 response.headers.get_content_charset() 获取真实编码。
- 结构探测先行：首次调用时，建议先 print(type(json_obj), json_obj) 或 pprint(json_obj) 查看数据形态，再决定取数逻辑。
- 错误处理不可省略：网络请求、HTTP 状态码、JSON 格式、字段缺失均可能中断流程，生产环境必须包裹 try-except。
- 密钥安全提示：示例中的 Ocp-Apim-Subscription-Key 属于敏感凭证，实际项目中应通过环境变量（os.getenv("WTO_API_KEY")）或配置文件管理，切勿硬编码提交至 Git。
掌握这一模式后，你可复用于绝大多数返回 JSON 的 Web API（如 World Bank、UN Data、政府开放平台等），快速构建结构化分析基础。
