单位换算器返回字段全解：ret_code 与 result_list 一文读懂
返回字段ret_coderesult_listAPI解析 # 单位换算器返回字段全解：ret_code 与 result_list 一文读懂
> 接口/接入点：免费单位换算 1690-1（单位换算）｜是否免费：是｜请求方式：POST/GET｜返回格式：JSON｜适用人群：已接入或准备接入的开发者｜阅读时间：约 6 分钟
## 核心要点
- 业务数据全部包裹在 `showapi_res_body` 内；系统级字段在 `showapi_res_*` 上。
- 成功/失败看 `ret_code`：`0` 成功（计次）、`-1` 失败（不扣费）。
- `result_list` 每项含 `result`(数值) / `result_str`(字符串) / `unit`(单位) / `type`(类别)——展示用 `result_str`，计算用 `result` 并做 `Number()` 转换。
## Why：为什么必须读懂返回结构
调用失败时报错信息藏在哪？换算结果到底取哪个字段？很多工单都源于「没看准返回层级」：`result` 在 `result_list[0]` 里，不在顶层。本文把结构拆清楚，避免你拿错字段、把数值当字符串拼接。
## What：返回结构速览
| 层级 | 字段 | 类型 | 说明 |
|------|------|------|------|
| 系统级 | `showapi_res_code` | int | 系统状态码，0 正常 |
| 系统级 | `showapi_res_error` | String | 系统错误信息 |
| 系统级 | `showapi_res_id` | String | 本次请求 ID |
| 系统级 | `showapi_fee_num` | int | 计次扣费计数（免费接口也计次） |
| 业务体 | `showapi_res_body` | Object | 业务数据容器 |
| 业务体 | `ret_code` | String | `0` 成功 / `-1` 失败 |
| 业务体 | `remark` | String | 返回说明，如「查询成功！」 |
| 业务体 | `result_list` | Object[] | 结果数组 |
`result_list` 单项：
| 字段 | 类型 | 说明 |
|------|------|------|
| `result` | 数值/字符串 | 换算结果（文档标 String，实测返回 Number，如 `0.01`） |
| `result_str` | String | 字符串形式结果，如 `"0.01"` |
| `unit` | String | 目标单位中文名，如「米」 |
| `type` | String | 类别代码，如 `longness` |
## How：正确解析返回
```python
import requests
def convert(num, frm, to, typ=None):
data = {"num": str(num), "from": frm, "to": to}
if typ:
data["type"] = typ
r = requests.post(
"https://route.showapi.com/1690-1",
params={"appKey": "YOUR_APPKEY"},
data=data, timeout=10,
)
body = r.json()["showapi_res_body"]
if body.get("ret_code") != "0":
raise RuntimeError(body.get("remark", "查询失败"))
item = body["result_list"][0]
# 展示：用字符串 result_str；计算：转数值
display = item["result_str"] + item["unit"]
value = float(item["result"]) # Number() 转换，兼容数值/字符串两种返回
return display, value
print(convert(1, "cm", "m", "longness")) # ('0.01米', 0.01)
```
```javascript
async function convert(num, frm, to, typ) {
const body = new URLSearchParams({ num: String(num), from: frm, to });
if (typ) body.set("type", typ);
const res = await fetch(`https://route.showapi.com/1690-1?appKey=YOUR_APPKEY`, {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body,
});
const json = await res.json();
const b = json.showapi_res_body;
if (b.ret_code !== "0") throw new Error(b.remark || "查询失败");
const it = b.result_list[0];
return { display: it.result_str + it.unit, value: Number(it.result) };
}
```
## 返回示例
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_id": "6a990ac7fb638c81388339f8",
"showapi_fee_num": 1,
"showapi_res_body": {
"ret_code": 0,
"remark": "查询成功！",
"result_list": [
{ "result": 0.01, "result_str": "0.01", "unit": "米", "type": "longness" }
]
}
}
```
## 进阶 / 边界
- `ret_code` 只有 `0` / `-1` 两态，**没有更细的错误码枚举**；失败原因看 `remark` 文案。
- `result` 类型不固定：文档写 String，实测返回 Number。不要写 `item.result + "米"`（可能拼成 `"0.01米"` 也可，但若后端改字符串格式会有坑）；统一用 `result_str + unit` 做展示。
- `showapi_fee_num` 在免费接口也会出现（计次），不代表收费，只是使用计数。
## FAQ
**Q1：怎么判断一次调用成功？**
A：先看系统级 `showapi_res_code == 0`，再看业务级 `showapi_res_body.ret_code == "0"`；两者都为成功才取 `result_list`。
**Q2：失败时有 result_list 吗？**
A：通常没有或为空，失败信息在 `remark`。代码里先判 `ret_code` 再取 `result_list[0]`，避免越界。
**Q3：`result` 和 `result_str` 数值会不一致吗？**
A：语义一致，只是类型不同（字符串 vs 数值）。展示用 `result_str`，计算用 `Number(result)`。
**Q4：为什么我拿到的是数组而不是单个对象？**
A：接口设计为 `result_list` 数组，便于未来扩展多条结果；当前单值换算返回长度 1 的数组，取 `[0]` 即可。
## 相关能力 / 下一步阅读
- [单位换算器：5 分钟接入（从注册到第一次单位换算）](https://www.showapi.com/guides/unit-convert-quickstart-1690)
- [换算精度与浮点结果怎么处理？result 与 result_str 的区别](https://www.showapi.com/guides/unit-convert-precision-1690)
- [单位换算器支持哪些单位？14 大类与完整单位清单](https://www.showapi.com/guides/unit-convert-supported-types-1690)
- **本系列共 12 篇**：查看[单位换算器（免费单位换算）指南总目录](https://www.showapi.com/guides/unit-convert-guides-1690)
