单位换算器参数怎么填？from/to 必填与常见报错排查
# 单位换算器参数怎么填？from/to 必填与常见报错排查
> 接口/接入点：免费单位换算 1690-1（单位换算）｜是否免费：是｜请求方式：POST/GET｜返回格式：JSON｜适用人群：调用报错或刚上手的开发者｜阅读时间：约 6 分钟
## 核心要点
- 三个核心参数：`num`(必填)、`from`(必填)、`to`(必填)；`type` 非必填但建议传，能帮接口定位单位类别。
- `from`/`to` 用单位**代码**（如 `cm`/`m`），不是中文名；且必须属于可互通的同一物理类别。
- 失败看 `ret_code=="-1"` 与 `remark` 文案；接口没有细粒度错误码，排查靠参数与单位清单。
## Why：多数报错都出在参数
「返回失败」「结果不对」八成是参数传错：`from`/`to` 漏了、用了中文名、或把长度单位拿去和温度单位配。本文把正确填法和常见坑一次讲清，少走弯路。
## What：参数速览
| 参数 | 必填 | 说明 |
|------|------|------|
| `num` | 是 | 待转换的数字，字符串形式，如 `"1"` |
| `from` | 是 | 源单位代码，如 `cm` |
| `to` | 是 | 目标单位代码，如 `m` |
| `type` | 否 | 14 类之一（longness/area/weight/volume/temperature/speed/time/pressure/power/angle/dataStorage/energy/density/work），传了定位更快 |
## 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":
# 失败：看 remark 文案做排查
raise RuntimeError(f"ret_code={body.get('ret_code')} remark={body.get('remark')}")
return body["result_list"][0]
# 正确：带 type，用代码
print(convert(100, "cm", "m", "longness")) # 1.0 米
```
```bash
# 正确示例
curl -X POST "https://route.showapi.com/1690-1?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "num=100&from=cm&to=m&type=longness"
```
## 常见报错与排查
| 现象 | 可能原因 | 排查 |
|------|---------|------|
| `ret_code=-1` | `from`/`to` 漏传或为空 | 确认三个必填都在；GET 时检查 URL 是否被正确编码 |
| 结果明显错 | `from`/`to` 用了中文名或错误代码 | 改用[支持的单位代码](https://www.showapi.com/guides/unit-convert-supported-types-1690) |
| 跨类无结果 | 长度单位配温度单位等 | 先确定 `type`，源/目标同属一类 |
| `num` 非数字 | 传了字母/空 | `num` 用纯数字字符串，如 `"1"`、`"12.5"` |
## 进阶 / 边界
- `type` 不传也能换，但传了更稳：某些单位代码跨类别重名（如「分」），带 `type` 可避免歧义。
- `num` 支持小数（如 `"0.5"`），但不支持带单位混写（如 `"1cm"`），数字和单位要分开。
- GET 调用时 `+`、中文等需 URL 编码，建议用库自带编码而非手拼。
## FAQ
**Q1：`from`/`to` 必须带 type 吗？**
A：不必，`type` 非必填。但单位代码跨类重名时带 `type` 能消除歧义，推荐传。
**Q2：能用中文单位名吗？**
A：不能，用代码（如 `m`/`kg`/`oC`）。中文名只用于展示，见[单位清单](https://www.showapi.com/guides/unit-convert-supported-types-1690)。
**Q3：失败有具体错误码吗？**
A：没有。`ret_code` 只有 `0`/`-1`，失败原因看 `remark` 文案。
**Q4：`num` 能传负数吗？**
A：物理量多为非负；温度等允许负值的类别（如摄氏度）可传负数字符串，是否支持以实际返回为准。
**Q5：一次能传多个 num 吗？**
A：1690-1 是单值接口，循环调用实现批量，见[科研/工程场景集成](https://www.showapi.com/guides/unit-convert-engineering-integration-1690)。
## 相关能力 / 下一步阅读
- [单位换算器支持哪些单位？14 大类与完整单位清单](https://www.showapi.com/guides/unit-convert-supported-types-1690)
- [单位换算器：5 分钟接入（从注册到第一次单位换算）](https://www.showapi.com/guides/unit-convert-quickstart-1690)
- [单位换算器返回字段全解：ret_code 与 result_list 一文读懂](https://www.showapi.com/guides/unit-convert-response-codes-1690)
- **本系列共 12 篇**：查看[单位换算器（免费单位换算）指南总目录](https://www.showapi.com/guides/unit-convert-guides-1690)
