外汇数据查询：5 分钟接入，从注册到第一条热门外汇列表
# 外汇数据查询：5 分钟接入，从注册到第一条热门外汇列表
> 接入点：热门外汇列表（1683-1） · 免费 · POST/GET · 返回 JSON · 适用：新注册用户、初级开发者 · 阅读时间：5 分钟
## TL;DR
- 外汇数据查询（apiCode=1683）是**免费**接口，注册即享基础调用档位，无需付费即可开始调用。
- 第一个接入点「热门外汇列表（1683-1）」**无需任何业务参数**，传 AppKey 即可返回约 35 个热门货币对编码与中文名。
- 用下方任意一段代码（Python / cURL / Node.js）替换 `YOUR_APPKEY` 即可跑通。
## Why：为什么先跑通这一个接入点
你刚注册完易源账号，想验证「这接口到底能不能用」。最受欢迎的入门姿势，就是先调通**最简单、零参数**的接入点——热门外汇列表。它不需要日期、不需要指定货币，返回的是一份固定的「可查货币对清单」，你的后续日线/分钟 K 线查询都要用这里的 `code`。先拿到这份清单，后面才不会传错编码。
## What：前置条件与接口速览
| 项 | 说明 |
|----|------|
| 接口地址 | `https://route.showapi.com/1683-1?appKey={your_appKey}` |
| 请求方式 | POST 或 GET |
| 返回格式 | JSON |
| 是否免费 | 是（注册即享基础档位，积分可兑换更高档位） |
| 业务参数 | 无（仅 Header `content-type`，可选） |
| 鉴权 | URL 中的 `appKey` |
| 数据性质 | 延迟数据，仅供学习分析，不得用于对外展示 |
## How：三步跑通
### 1. 获取 AppKey
登录易源控制台 →「我的账号」→「AppKey 管理」，复制你的 AppKey。
### 2. 发起请求（三选一）
**Python（requests）**
```python
import requests
url = "https://route.showapi.com/1683-1"
params = {"appKey": "YOUR_APPKEY"} # 也可放在 URL 中
try:
r = requests.post(url, data=params, timeout=10)
r.raise_for_status()
data = r.json()
except requests.RequestException as e:
print("请求失败：", e)
raise
if data.get("showapi_res_code") != 0:
print("业务错误：", data.get("showapi_res_error"))
else:
body = data["showapi_res_body"]
print("ret_code:", body.get("ret_code"))
print("热门货币对数量:", len(body.get("forexList", [])))
for item in body["forexList"][:5]:
print(item["code"], item["forexName"])
```
**cURL**
```bash
curl -X POST "https://route.showapi.com/1683-1?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded"
```
**Node.js（fetch）**
```javascript
const url = "https://route.showapi.com/1683-1";
const body = new URLSearchParams({ appKey: "YOUR_APPKEY" });
try {
const resp = await fetch(url, { method: "POST", body, signal: AbortSignal.timeout(10000) });
const data = await resp.json();
if (data.showapi_res_code !== 0) {
console.error("业务错误：", data.showapi_res_error);
} else {
const list = data.showapi_res_body.forexList;
console.log("ret_code:", data.showapi_res_body.ret_code, "数量:", list.length);
list.slice(0, 5).forEach(i => console.log(i.code, i.forexName));
}
} catch (e) {
console.error("请求失败：", e);
}
```
### 3. 解析返回
返回体在 `showapi_res_body` 内，`forexList` 是对象数组，每个元素含 `code`（如 `USDCNY`）和 `forexName`（如 `美元兑人民币`）。
## 返回示例（节选）
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_id": "ce135f6739294c63be0c021b76b6fbff",
"showapi_res_body": {
"ret_code": 0,
"forexList": [
{ "code": "DINIW", "forexName": "美元指数" },
{ "code": "USDCNY", "forexName": "美元兑人民币" },
{ "code": "USDJPY", "forexName": "美元兑日元" }
]
}
}
```
## 进阶 / 边界
- **拿到 `code` 后做什么**：日线历史（1683-2）、分钟 K 线（1683-3）的 `code` 参数都来自这份列表，务必用列表里真实存在的编码。
- **免费但有档位限制**：默认档位对调用频次/总量有限制，高频场景可用平台积分兑换更高档位（具体见官方档位说明）。
## FAQ
**Q1：返回 showapi_res_code 非 0 是什么情况？**
A：顶层 `showapi_res_code` 非 0 通常是鉴权或系统级问题，先看 `showapi_res_error` 文案；业务级成功以 `showapi_res_body.ret_code == 0` 为准。
**Q2：热门外汇列表每次返回都一样吗？**
A：该接入点返回的是固定的可查货币对清单，结构稳定；它反映的是「可查哪些编码」，不是实时行情。
**Q3：免费接口为什么还有档位限制？**
A：为防止滥用，注册默认档位对调用量有限制，可用积分兑换更高档位，具体以官方档位说明为准。
**Q4：这个数据能直接展示给用户吗？**
A：不能。文档明确：数据为延迟数据，仅供学习分析，不得用于对外展示。
## 下一步阅读
- [外汇数据查询：返回字段与数据结构全解](https://www.showapi.com/guides/forex-response-fields-1683)
- [外汇数据查询：热门外汇列表接入点详解](https://www.showapi.com/guides/forex-hotlist-guide-1683)
- [外汇数据查询：日线历史查询接入点实战](https://www.showapi.com/guides/forex-daily-history-1683)
- **本系列共 13 篇**：查看[外汇数据查询指南总目录](https://www.showapi.com/guides/forex-guides-1683)
