国际原油价格查询返回字段全解：nowPrice / diff_rate / stockNum 一文读懂
国际原油价格查询原油价格APIWTI原油布伦特原油免费接口 # 国际原油价格查询返回字段全解：nowPrice / diff_rate / stockNum 一文读懂
> 接口：国际原油价格查询（apiCode=1108，接入点 1108-1）｜ 免费 ｜ 请求方式 POST/GET ｜ 返回 JSON ｜ 适用人群：已接入或准备接入的开发者 ｜ 阅读时间：约 6 分钟
## 核心要点
- 业务数据全部在 `showapi_res_body` 对象内，共 11 个字段。
- 类型混合：`nowPrice` 与 `ret_code` 是 Number，其余价格字段均为 String，解析时务必注意。
- `diff_rate` 是带百分号的字符串（如 `"1.13%"`），`stockNum` 单位为千桶。
## Why
接好接口只是第一步，读懂返回结构才能正确展示和计算。国际原油价格查询的返回字段不多，但有两点容易踩坑：一是 `nowPrice` 是数字、其它价格字段是字符串；二是涨跌幅 `diff_rate` 已经带了百分号、不能当纯数字再乘 100。本文把 11 个字段的类型、单位、含义一次性讲清，作为全系列的事实底座页。
## What
| 项目 | 说明 |
|------|------|
| 业务数据容器 | `showapi_res_body`（Object） |
| 字段总数 | 11 个（含 `ret_code`） |
| 系统级外层字段 | `showapi_res_code` / `showapi_res_error` / `showapi_res_id` |
| 成功判定 | `showapi_res_body.ret_code == 0` |
## How
### 返回字段对照表
| 字段 | 类型 | 示例 | 含义 / 单位 |
|------|------|------|------------|
| `nowPrice` | Number | `44.94` | 当前价格，单位 美元/桶 |
| `yestoday_closePrice` | String | `"44.44"` | 昨日结算价 |
| `today_openPrice` | String | `"45.05"` | 今日开盘价 |
| `todayMax` | String | `"45.62"` | 今日最高价 |
| `todayMin` | String | `"44.72"` | 今日最低价 |
| `diff_num` | String | `"0.5"` | 涨跌金额（相对昨日结算价） |
| `diff_rate` | String | `"1.13%"` | 涨跌幅度，已带百分号 |
| `time` | String | `"2025-02-11 14:05:34"` | 数据发布时间 |
| `stockNum` | String | `"10045"` | 持仓量，单位 千桶 |
| `name` | String | `"WTI原油(NYMEX原油)"` | 原油名称（随 `code` 变化） |
| `ret_code` | Number | `0` | 0 为成功，其他为失败 |
### 解析示例（Python）
```python
import requests
APP_KEY = "YOUR_APPKEY"
resp = requests.get(
"https://route.showapi.com/1108-1",
params={"appKey": APP_KEY, "code": "blt"},
timeout=10,
).json()
body = resp["showapi_res_body"]
if body["ret_code"] != 0:
raise SystemExit("业务失败")
# nowPrice 已是数字，可直接运算
now = body["nowPrice"]
# 其余价格字段是字符串，需转换
yest_close = float(body["yestoday_closePrice"])
high = float(body["todayMax"])
low = float(body["todayMin"])
# diff_rate 带百分号，去掉后转浮点
rate = float(body["diff_rate"].rstrip("%"))
print(f"{body['name']} 当前 {now} 美元/桶，涨跌 {body['diff_rate']}")
print(f"区间 {low}~{high}，幅度 {rate}%")
```
## 返回示例与解析
```json
{
"showapi_res_code": 0,
"showapi_res_body": {
"ret_code": 0,
"nowPrice": 44.94,
"yestoday_closePrice": "44.44",
"today_openPrice": "45.05",
"todayMax": "45.62",
"todayMin": "44.72",
"diff_num": "0.5",
"diff_rate": "1.13%",
"time": "2025-02-11 14:05:34",
"stockNum": "10045",
"name": "WTI原油(NYMEX原油)"
}
}
```
> 注意外层 `showapi_res_code`（系统级）与内层 `ret_code`（业务级）是两个不同字段，成功判断以内层 `ret_code == 0` 为准。
## 进阶 / 边界
- **类型转换是必做项**：除 `nowPrice`、`ret_code` 外，价格字段都是字符串，存库或计算前请先 `float()`。
- **`diff_rate` 已是百分比文本**：展示可直接用；若要计算，去掉 `%` 再转数字，不要重复乘 100。
- **`name` 随 `code` 变化**：传 `wti` 返回「WTI原油(NYMEX原油)」，传 `blt` 返回布伦特相关名称，用它做界面标题最稳妥。
## FAQ
**Q：ret_code 和 showapi_res_code 有什么区别？**
`showapi_res_code` 是系统级返回码（网络/网关层），`ret_code` 在 `showapi_res_body` 内、代表业务结果。业务成功以 `ret_code == 0` 判断。
**Q：diff_rate 是相对什么的涨跌幅？**
相对昨日结算价（`yestoday_closePrice`）计算，字段说明已标注。
**Q：为什么价格有的是数字、有的是字符串？**
接口对 `nowPrice`、`ret_code` 返回数字类型，其余价格字段返回字符串类型；这是文档给定的实际结构，解析时需分别处理。
**Q：stockNum 的单位是什么？**
持仓量，单位为千桶（字段说明标注「单位千桶」）。
**Q：time 是数据发布时间还是请求时间？**
是数据发布时间（字段说明标注「发布时间」），更新频率为每小时整点。
## 相关能力 / 下一步阅读
- [国际原油价格查询：5 分钟从注册到拿到第一条 WTI 报价](https://www.showapi.com/guides/crude-oil-price-quickstart-1108)
- [国际原油价格查询：原油涨跌监控与趋势预警搭建指南](https://www.showapi.com/guides/crude-oil-price-alert-1108)
- [国际原油价格查询：ret_code 与常见调用错误排查](https://www.showapi.com/guides/crude-oil-price-error-handling-1108)
- **本系列共 12 篇**：查看[国际原油价格查询官方指南总目录](https://www.showapi.com/guides/crude-oil-price-guides-1108)
