银行汇率查询：5 分钟从注册跑到第一次调用
约 12 分钟 入门银行汇率查询API快速接入Python示例免费接口
# 银行汇率查询：5 分钟从注册跑到第一次调用
接口：银行汇率查询（apiCode=105）· 接入点：汇率查询（105-30）· 免费（L0 基础版 100 次/天、1 QPS）· 请求方式：POST / GET · 返回格式：JSON · 适用人群：新注册用户、初级开发者 · 阅读时间：约 5 分钟 · 最后实测核对：2026-09-18
## 核心要点
- 注册 ShowAPI 账号后，在控制台创建应用拿到 AppKey，把 AppKey 拼到请求地址的 query 里就能调用，不需要额外签名。
- 汇率查询接入点（105-30）的 `code` 参数可选：不传返回全部货币，传 `code=USD` 只返回这一种。
- 业务数据在 `showapi_res_body` 里，`showapi_res_body.ret_code` 为 0 才代表本次查询成功。
## 你在什么场景会用到它
给海外商品标价、算留学学费折合人民币多少、做出境预算，都需要一份外币兑人民币的牌价。银行汇率查询接口直接返回各家银行的外汇牌价，注册即可调用，不用自己去找挂牌数据再整理成表。
这篇的目标很具体：让你在 5 分钟内发出第一次请求，看到真实的牌价数字。
## 前置条件与接口速览
开始前需要两样东西：一个 ShowAPI 账号、一个应用对应的 AppKey。
| 项目 | 说明 |
|------|------|
| 接口地址 | `https://route.showapi.com/105-30?appKey={your_appKey}` |
| 接入点 | 汇率查询（105-30） |
| 请求方式 | POST / GET，同步请求-响应 |
| 鉴权 | query 参数 `appKey`，在控制台获取 |
| 计费 | 免费接口，注册即享 L0 基础版（100 次/天、1 QPS）；积分可升级更高档位 |
| 返回格式 | JSON，业务数据封装在 `showapi_res_body` 内 |
| 超时设置 | OpenAPI 文档标注 `x-read-timeout` 15 秒、`x-connect-timeout` 15 秒 |
| 集成能力 | 接口级 MCP 服务、标准 OpenAPI 3.0 文档（覆盖全部 4 个接入点） |
## 分三步跑通
### 步骤 1：拿到 AppKey
登录 ShowAPI 控制台，创建一个应用，把它的 AppKey 复制出来。AppKey 是唯一的身份凭据，代码里用占位符写成 `YOUR_APPKEY`，不要提交到公开仓库。
### 步骤 2：发起第一次调用
下面三段代码查的是美元牌价。把 `YOUR_APPKEY` 换成你自己的值就能直接运行。
Python（requests）：
```python
import requests
url = "https://route.showapi.com/105-30"
params = {"appKey": "YOUR_APPKEY"} # AppKey 走 query
data = {"code": "USD"} # 业务参数走表单；不传 code 返回全部货币
try:
resp = requests.post(url, params=params, data=data, timeout=15)
resp.raise_for_status()
js = resp.json()
if js.get("showapi_res_code") == 0 and js["showapi_res_body"].get("ret_code") == 0:
for item in js["showapi_res_body"]["list"]:
print(item["name"], item["code"], "现汇卖出价", item["hui_out"])
else:
print("调用失败：", js.get("showapi_res_error"),
js["showapi_res_body"].get("ret_code"))
except requests.RequestException as exc:
print("请求异常：", exc)
```
cURL：
```bash
curl -X POST "https://route.showapi.com/105-30?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "code=USD"
```
Node.js（fetch，Node 18+）：
```javascript
const url = "https://route.showapi.com/105-30?appKey=YOUR_APPKEY";
const body = new URLSearchParams({ code: "USD" });
const res = await fetch(url, {
method: "POST",
body,
headers: { "content-type": "application/x-www-form-urlencoded" },
signal: AbortSignal.timeout(15000) // 对齐文档的 15 秒读超时
});
const js = await res.json();
if (js.showapi_res_code === 0 && js.showapi_res_body.ret_code === 0) {
for (const item of js.showapi_res_body.list) {
console.log(item.name, item.code, "现汇卖出价", item.hui_out);
}
} else {
console.error("调用失败：", js.showapi_res_error, js.showapi_res_body.ret_code);
}
```
### 步骤 3：读取结果
业务数据都在 `showapi_res_body.list` 数组里，每条对应一种货币。判断顺序是：先看系统级 `showapi_res_code` 是否为 0，再看业务级 `showapi_res_body.ret_code` 是否为 0，两者都通过再读字段。
## 返回示例与解析
以下是 2026-09-18 实测调用 `105-30?code=USD` 的真实返回，删去了请求标识字段：
```json
{
"showapi_res_error": "",
"showapi_res_code": 0,
"showapi_fee_num": 1,
"showapi_res_body": {
"listSize": 1,
"ret_code": 0,
"list": [
{
"name": "美元",
"code": "USD",
"hui_in": "669.61",
"chao_in": "669.61",
"hui_out": "672.42",
"chao_out": "672.42",
"zhesuan": "675.21",
"day": "2026-09-18",
"time": "09:16:23"
}
]
}
}
```
| 字段 | 含义 |
|------|------|
| `listSize` | 本次返回的数据条数 |
| `list[].name` | 货币中文名称 |
| `list[].code` | 货币简码 |
| `list[].hui_in` | 现汇买入价 |
| `list[].chao_in` | 现钞买入价 |
| `list[].hui_out` | 现汇卖出价 |
| `list[].chao_out` | 现钞卖出价 |
| `list[].zhesuan` | 中行折算价 |
| `list[].day` / `list[].time` | 牌价的发布日 / 发布时间 |
| `list[].ret_code`（业务级） | 0 为成功，其他为失败 |
五个价位字段都以字符串返回，例如 `"669.61"`，参与计算前先转成数值。
## 返回值里的两个细节
**不传 `code` 时返回 46 条记录。** 2026-09-18 实测：不传 `code` 时 `listSize` 为 46，包含 45 种外币加人民币（CNY）。这 46 条记录的 `day` 都是 `2026-09-18`、`time` 都是 `09:16:23`，同一批返回共用同一个时间戳，所以可以用 `day` + `time` 判断数据快照的新鲜度。
**`code` 只接受货币简码。** 传 `code=USD` 返回 1 条；需要一次拿全量就先不传，拿到结果后再在本地按需筛选。
## FAQ
**Q1：`showapi_res_code` 和 `ret_code` 有什么区别？**
`showapi_res_code` 是系统级状态码，0 表示接口调用通道正常；`ret_code` 是业务级状态码，位于 `showapi_res_body` 内，0 表示本次查询成功。两者都为 0 才算整体成功。
**Q2：为什么价位是字符串而不是数字？**
接口对价位字段统一以字符串返回，例如 `"669.61"`。读取时按字符串处理，需要计算时自行转浮点并决定保留几位小数。
**Q3：免费接口有调用次数限制吗？**
免费接口注册即享 L0 基础版，每日 100 次、并发 1 QPS，长期有效。用平台积分可升级到 L1~L4 更高档位，具体额度见免费接口页。
**Q4：这些牌价是实时汇率吗？**
不是。产品说明写明延迟时长无法固定，接口返回的是银行上一周期或上两周期的数据，不返回实时汇率；接入点文档同样标注「数据源自网络，有数分钟延迟，非投资建议，数据分析参考」。实际交易汇率以当地银行为准。
**Q5：`code` 传人民币 CNY 会返回什么？**
实测会返回 1 条记录，五个价位均为 `"100"`。人民币是这套牌价的折算基准。
## 下一步阅读
- [银行汇率查询返回字段全解（五大价位 / 两层状态码 / 空值情况）](https://www.showapi.com/guides/exchange-rate-fields-105)：把每个字段的含义与空值处理一次讲清。
- [银行汇率查询：汇率转换只需 3 个必填参数](https://www.showapi.com/guides/exchange-rate-convert-guide-105)：不想自己算金额时，直接让接口换算。
- [银行汇率查询：L0 档位每天 100 次，缓存该缓存什么](https://www.showapi.com/guides/exchange-rate-cache-105)：免费档位下的调用额度和缓存设计。
- **本系列共 13 篇**：查看[银行汇率查询指南总目录](https://www.showapi.com/guides/exchange-rate-guides-105)
