单位换算器：5 分钟接入（从注册到第一次单位换算）
# 单位换算器：5 分钟接入（从注册到第一次单位换算）
> 接口/接入点：免费单位换算 1690-1（单位换算）｜是否免费：是（有档位限制）｜请求方式：POST/GET｜返回格式：JSON｜适用人群：新注册用户、初级开发者｜阅读时间：约 5 分钟
## 核心要点
- 单位换算器是**免费**接口，注册后拿 AppKey 即可调用，单次换算传 `num`/`from`/`to` 三个参数。
- 返回包裹在 `showapi_res_body` 内，看 `ret_code`（0 成功 / -1 失败）判断是否查到。
- 一条 `1cm → 米` 的调用，替换 AppKey 就能直接跑通。
## Why：这跟我有什么关系
做科研、工程、物流、教育或日常工具时，经常要把「厘米」换成「米」、「摄氏度」换成「华氏度」、「GB」换成「TB」。自己写换算系数容易漏单位、踩进制坑（1024 vs 1000）。单位换算器把 14 大类、上百个单位的换算都封装好，调一个接口就拿到准确结果，省去维护系数表。
## What：前置条件与接口速览
| 项 | 值 |
|----|----|
| 接口地址 | `https://route.showapi.com/1690-1?appKey={your_appKey}` |
| 接入点 | 单位换算（1690-1） |
| 请求方式 | POST / GET |
| 鉴权 | AppKey（查询参数 `appKey`） |
| 计费 | 免费，设有使用档位限制 |
| 更新频率 | 持续更新，每次返回最新数据 |
| 集成能力 | MCP 服务、OpenAPI 文档（YAML/JSON） |
请求参数：`num`(String,必填) 待转换数字；`from`(String,必填) 源单位；`to`(String,必填) 目标单位；`type`(String,非必填) 14 类之一（长度 longness / 面积 area / 质量 weight / 体积 volume / 温度 temperature / 速度 speed / 时间 time / 压力 pressure / 功率 power / 角度 angle / 数据存储 dataStorage / 力 energy / 密度 density / 功·能·热 work）。`type` 可不传，但传了能帮接口更快定位单位类别。
## How：第一次调用
### Python（requests）
```python
import requests
url = "https://route.showapi.com/1690-1"
params = {"appKey": "YOUR_APPKEY"}
data = {
"num": "1",
"from": "cm",
"to": "m",
"type": "longness",
}
try:
r = requests.post(url, params=params, data=data, timeout=10)
r.raise_for_status()
body = r.json()["showapi_res_body"]
if body.get("ret_code") != "0":
print("查询失败:", body.get("remark"))
else:
for item in body["result_list"]:
# item["result_str"] 是字符串结果，如 "0.01"
# item["unit"] 是目标单位，如 "米"
print(item["result_str"], item["unit"])
except requests.RequestException as e:
print("请求异常:", e)
```
### Node.js（fetch + 超时）
```javascript
const ctrl = new AbortController();
const timer = setTimeout(() => ctrl.abort(), 10000);
try {
const res = await fetch(
`https://route.showapi.com/1690-1?appKey=YOUR_APPKEY`,
{
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({ num: "1", from: "cm", to: "m", type: "longness" }),
signal: ctrl.signal,
}
);
const json = await res.json();
const body = json.showapi_res_body;
if (body.ret_code !== "0") {
console.error("查询失败:", body.remark);
} else {
body.result_list.forEach((i) => console.log(i.result_str, i.unit));
}
} catch (e) {
console.error("请求异常:", e);
} finally {
clearTimeout(timer);
}
```
### cURL
```bash
curl -X POST "https://route.showapi.com/1690-1?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "num=1&from=cm&to=m&type=longness"
```
> 把 `YOUR_APPKEY` 换成你在 [AppKey 管理](https://www.showapi.com/console#/myApp) 拿到的真实密钥即可运行。
## 返回示例与解析
```json
{
"showapi_res_code": 0,
"showapi_res_body": {
"ret_code": 0,
"remark": "查询成功！",
"result_list": [
{ "result": 0.01, "result_str": "0.01", "unit": "米", "type": "longness" }
]
}
}
```
- `ret_code: 0` 表示查询成功（会计次扣费）；`remark` 是说明文案。
- `result_list` 是数组，每项含 `result`(数值结果)、`result_str`(字符串结果)、`unit`(目标单位)、`type`(类别)。
- ⚠️ 注意：`result` 字段文档标注为字符串，但实测返回为数值（如 `0.01`）。展示用 `result_str`、计算用 `result` 时记得做 `Number()` 转换，详见[换算精度与浮点结果怎么处理？](https://www.showapi.com/guides/unit-convert-precision-1690)。
## 进阶 / 边界
- 免费接口有**档位限制**（防滥用），具体档位以[官方档位说明](https://www.showapi.com/free-api)为准，不要假设无限调用。
- `from` 与 `to` 必须属于可互通的同一物理类别；跨类（如长度→温度）接口无法换算，需自行先选对 `type`。
- 想看接口支持的全部单位代码，见[单位换算器支持哪些单位？](https://www.showapi.com/guides/unit-convert-supported-types-1690)。
## FAQ
**Q1：AppKey 在哪拿？**
A：登录易源后在 [AppKey 管理](https://www.showapi.com/console#/myApp) 创建应用即可拿到，免费接口注册后默认可用。
**Q2：免费接口要不要钱？**
A：单位换算器本身是免费服务，但设有使用档位限制以防滥用，超出档位需看官方说明，具体数字以[档位说明页](https://www.showapi.com/free-api)为准。
**Q3：GET 和 POST 都能用吗？**
A：都能。POST 用表单（`content-type: application/x-www-form-urlencoded`），参数放 body；GET 把参数拼到 URL 查询串（含 `appKey`）。
**Q4：返回里 `result` 和 `result_str` 用哪个？**
A：要给用户看用 `result_str`（字符串，如 "0.01"）；要继续做数值计算用 `result`，但注意它可能以数值返回，做 `Number()` 转换更稳妥。
**Q5：一次能换算多个数吗？**
A：1690-1 是单值接口，一次传一个 `num`。要批量请循环调用，参考[科研/工程场景如何集成单位换算器？](https://www.showapi.com/guides/unit-convert-engineering-integration-1690)。
## 相关能力 / 下一步阅读
- [单位换算器返回字段全解：ret_code 与 result_list 一文读懂](https://www.showapi.com/guides/unit-convert-response-codes-1690)
- [单位换算器支持哪些单位？14 大类与完整单位清单](https://www.showapi.com/guides/unit-convert-supported-types-1690)
- [单位换算器参数怎么填？from/to 必填与常见报错排查](https://www.showapi.com/guides/unit-convert-params-errors-1690)
- **本系列共 12 篇**：查看[单位换算器（免费单位换算）指南总目录](https://www.showapi.com/guides/unit-convert-guides-1690)
