银行汇率查询：5 分钟接入——从注册到第一次实时汇率查询
银行汇率查询API快速接入Python示例免费接口 # 银行汇率查询：5 分钟接入——从注册到第一次实时汇率查询
> 接口：银行汇率查询（apiCode=105）· 接入点：汇率查询（105-30）· 免费 · 请求方式：POST/GET · 返回格式：JSON · 适用人群：新注册用户 / 初级开发者 · 阅读时间：约 5 分钟
## TL;DR
- 注册 ShowAPI 账号 → 在控制台拿到 AppKey → 把 AppKey 填进请求地址即可调用。
- 实时牌价接入点 `105-30` 支持「不传 code 查全部 / 传 code 查单个货币」。
- 返回包在 `showapi_res_body` 内，业务级 `ret_code = 0` 才代表查询成功。
## Why
做跨境结算、留学缴费、海外商品价格展示时，你都需要一份「主流银行外汇牌价」。银行汇率查询接口直接返回中国银行的现汇/现钞买入卖出价与中行折算价，注册即可免费调用，省去你自己爬网页、解析表格的麻烦。
本篇目标：让你在 5 分钟内跑通第一次调用，看到真实牌价数据。
## What
| 项目 | 说明 |
|------|------|
| 接口地址 | `https://route.showapi.com/105-30?appKey=YOUR_APPKEY` |
| 接入点 | 汇率查询（105-30） |
| 请求方式 | POST / GET |
| 鉴权 | 地址中的 `appKey`（在控制台「我的应用」获取） |
| 计费 | 免费，但有使用档次限制（防滥用） |
| 更新频率 | 每 10s 更新一次 |
| 集成能力 | 支持 MCP、OpenAPI 3.0（覆盖全部 4 个接入点） |
## How
### 步骤 1：获取 AppKey
登录 [ShowAPI 控制台](https://www.showapi.com/console#/myApp)，创建一个应用，复制它的 AppKey。
### 步骤 2：发起第一次调用（查询美元牌价）
**Python（requests）**
```python
import requests
url = "https://route.showapi.com/105-30"
params = {"appKey": "YOUR_APPKEY"} # AppKey 放 query
data = {"code": "USD"} # 业务参数放表单；不传 code 则返回全部
try:
r = requests.post(url, params=params, data=data, timeout=10)
r.raise_for_status()
js = r.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"))
except requests.RequestException as e:
print("请求异常：", e)
```
**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）**
```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" }
});
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);
}
}
```
### 步骤 3：解析返回
业务数据都在 `showapi_res_body.list` 数组里，每条是一个货币的牌价对象。先判断 `showapi_res_code`（系统级）和 `ret_code`（业务级）都为 0，再读取字段。
## 返回示例与解析
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_body": {
"ret_code": 0,
"listSize": 1,
"list": [
{ "name": "美元", "code": "USD", "hui_in": "663.94", "chao_in": "658.62",
"hui_out": "666.6", "chao_out": "666.6", "zhesuan": "664.96",
"day": "2016-07-01", "time": "11:58:01" }
]
}
}
```
| 字段 | 含义 |
|------|------|
| `hui_in` | 现汇买入价 |
| `chao_in` | 现钞买入价 |
| `hui_out` | 现汇卖出价 |
| `chao_out` | 现钞卖出价 |
| `zhesuan` | 中行折算价 |
| `day` / `time` | 牌价发布日期 / 时间 |
> 注意：各价位字段以**字符串**返回（如 `"663.94"`），参与计算前请先转数值。
## 进阶 / 边界
- 不传 `code` 时接口返回全部已支持货币（约 26 种），首次接入可先拉全量了解支持范围。
- 部分小众货币某些价位可能为空字符串（如示例中的阿联酋迪拉姆无现汇买入价），前端展示要做空值兜底。
- 免费接口设使用档次限制，高频轮询请配合[本地缓存](https://www.showapi.com/guides/exchange-rate-cache-105)。
## FAQ
**Q：返回里的 ret_code 和 showapi_res_code 有什么区别？**
ret_code 是业务级状态码，位于 showapi_res_body 内，0 表示本次查询成功；showapi_res_code 是系统级状态码，0 表示接口调用通道正常。两者都为 0 才算整体成功。
**Q：为什么我拿到的是字符串而不是数字？**
文档中价位字段虽部分标注为 Number，但示例返回均为字符串（如 "663.94"）。请按字符串读取，需要计算时自行 `float()` / `parseFloat()`。
**Q：免费接口有调用次数限制吗？**
注册后默认可免费调用，但为防滥用设有使用档次限制，具体档位以官方积分与档位说明为准，文档未给出固定数值。
**Q：数据实时吗？能用于交易吗？**
牌价每 10s 更新，但数据源自网络、有数分钟延迟，仅供参考，实际交易以当地银行柜台为准，非投资建议。
## 相关能力 / 下一步阅读
- [银行汇率查询：返回字段与状态码全解](https://www.showapi.com/guides/exchange-rate-fields-105)
- [银行汇率查询：用"汇率转换"接入点把指定金额换算成任意外币](https://www.showapi.com/guides/exchange-rate-convert-guide-105)
- **本系列共 13 篇**：查看[银行汇率查询指南总目录](https://www.showapi.com/guides/exchange-rate-guides-105)
