1. 技术简介
沪深港股历史 K 线数据查询 API 是一种面向开发者与量化研究人员的标准化行情数据接口服务。通过传入股票代码（code）和时间参数（time），接口返回指定区间的 K 线数据列表，包含开盘价、收盘价、最高价、最低价、成交量等核心字段，可直接用于绘制日/周/月/分钟级走势图，支撑回测策略、财报分析、教学演示等场景。
接口以 RESTful GET 方式提供，返回 JSON 格式数据，支持前复权（qfq）、后复权（hfq）与不复权（bfq）三种数据模式，覆盖 A 股与港股代码段。
2. 能力概览
| 维度 | 说明 |
|---|---|
| 数据来源 | 沪深两市 + 港股历史 K 线 |
| 周期粒度 | 5 分钟 / 30 分钟 / 60 分钟 / 日 / 周 / 月（港股仅支持日、周、月） |
| 复权方式 | 不复权（bfq，默认）/ 前复权（qfq）/ 后复权（hfq），仅日/周/月周期生效 |
| 时间范围 | 通过 beginDay 指定起始日期（yyyyMMdd），结束日期默认为当前时间 |
| 返回结构 | 外层含 showapi_res_code、showapi_res_body；body 内含 dataList（K 线数组）与元信息（code、name、market、count） |
| 认证方式 | 支持 APPCODE 简单认证与 AppKey+AppSecret 签名认证两种方式 |
3. 适用场景
- 个人投资学习：对历史走势做技术分析，练习均线/布林带/MACD 等指标计算
- 量化策略回测：以日 K 或分钟 K 为输入，验证策略在历史数据上的表现
- 数据可视化：在前端图表库（ECharts、D3、AntV）中渲染蜡烛图
- 金融教育 / 课程：提供历史数据样例供教学演示
- 内部研报工具：作为数据源之一辅助人工分析，不可直接用于对外展示或投资建议
注意：商品页明确标注「本接口数据仅用于学习分析，不得用于对外展示」，请在合规范围内使用。
4. 接入流程
- 获取商品：在阿里云云市场找到「沪深港股历史数据查询分析服务」，完成订购并获取 AppKey 与 AppCode。
- 选择认证方式：简单调用用 APPCODE（Header 带
Authorization: APPCODE <your_appcode>）；对安全性要求更高时用 AppKey + AppSecret 签名。 - 构造请求：以 GET 方式请求 K 线接口路径，携带 Query 参数。
- 解析响应：判断外层
showapi_res_code为0时，读取showapi_res_body.dataList。 - 异常处理：
showapi_res_code非 0 或非 200 HTTP 状态时，参考第 9 章错误码排查。
5. 调用示例与返回结构
5.1 请求参数（Query）
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
code |
string | Y | 沪深/港股股票代码，如 600004 |
time |
string | N | K 线周期：5（默认）/ 30 / 60 / day / week / month；港股不支持 5/30/60 分钟 |
beginDay |
string | N | 起始日期，格式 yyyyMMdd，不传默认当天；结束日期固定为当前时间 |
type |
string | N | 复权方式：bfq（默认）/ qfq / hfq，仅 day/week/month 周期生效 |
5.2 多语言调用示例
以下示例使用
YOUR_APPCODE占位，实际替换为你在控制台获取的 AppCode。
curl
curl -X GET "K_LINE_API_ENDPOINT/realtime-k" \
-H "Authorization: APPCODE YOUR_APPCODE" \
-H "Content-Type: application/json; charset=utf-8" \
-d "code=600004&time=day&beginDay=20190801&type=bfq"
Python
import requests
url = "K_LINE_API_ENDPOINT/realtime-k"
headers = {
"Authorization": f"APPCODE YOUR_APPCODE",
"Content-Type": "application/json; charset=utf-8"
}
params = {
"code": "600004",
"time": "day",
"beginDay": "20190801",
"type": "bfq"
}
resp = requests.get(url, headers=headers, params=params, timeout=10)
data = resp.json()
if str(data.get("showapi_res_code")) == "0":
body = data["showapi_res_body"]
for kline in body["dataList"]:
print(kline["time"], kline["open"], kline["close"], kline["volumn"])
else:
print("调用失败:", data.get("showapi_res_msg"))
Java（伪代码示意，HttpUtils 请从阿里云文档获取）
Map<String, String> headers = new HashMap<>();
headers.put("Authorization", "APPCODE YOUR_APPCODE");
Map<String, String> querys = new HashMap<>();
querys.put("code", "600004");
querys.put("time", "day");
querys.put("beginDay", "20190801");
querys.put("type", "bfq");
HttpResponse response = HttpUtils.doGet(host, "/realtime-k", "GET", headers, querys);
5.3 返回结构
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_body": {
"dataList": [
{
"min": "14.910",
"open": "14.910",
"volumn": "53486.000",
"time": "20161110",
"max": "15.320",
"close": "15.170"
},
{
"min": "14.680",
"open": "15.040",
"volumn": "57193.000",
"time": "20161109",
"max": "15.070",
"close": "14.830"
}
],
"ret_code": 0,
"market": "sh",
"count": "8",
"name": "白云机场",
"code": "600004"
}
}
| 字段 | 说明 |
|---|---|
dataList[].time |
时间点；分钟 K 线精确到分钟，日/周/月精确到日 |
dataList[].open / close |
区间开/收盘价 |
dataList[].max / min |
区间最高/最低价 |
dataList[].volumn |
区间成交手数总和 |
market |
所属市场标识（sh / sz / hk） |
count |
返回 K 线数据总条数 |
6. 在线调试实录
在阿里云云市场商品页右侧的「API 调试」模块中，可以直接填写参数并点击「发起请求」。以下是一次日 K 线调试的典型过程：
- 参数填写：
code=600004、time=day、beginDay=20190801、type=bfq - 点击「发起请求」
- 响应面板显示 JSON，外层
showapi_res_code=0 dataList返回 8 条日线记录（2016 年 11 月 7 日～10 日）- 用 ECharts 将
dataList映射为蜡烛图，横轴为time，纵轴为open/close/max/min
提示：账户初始包含 100 次调用（30 天有效），足以完成调试验证；更高调用量请按资源包档位使用。
7. 调用限制与规范
| 项目 | 说明 |
|---|---|
| 扣减规则 | HTTP 响应 200 时扣减次数；非 200 不扣费 |
| 账户配额 | 初始 100 次（30 天有效），更高调用量按资源包档位开通 |
| 资源包档位 | 0.1 元/30 次、9.9 元/3000 次、50 元/20000 次、299 元/20 万次、999 元/100 万次、2999 元/400 万次、5999 元/1000 万次、9999 元/2000 万次 |
| 余量预警 | 余量降至（历史余量+当前资源包）×20% 时触发提醒，每 3 天一次 |
| 过期提醒 | 资源包到期前 6~7 天发送一次（仅对有余量的资源包） |
| 调用地址 | 以控制台实际显示为准（网关地址可能随版本更新变化） |
QPS 与并发上限未在商品页明确公示，建议批量任务做限流控制（如 1 req/s）避免触发网关限流，具体以控制台实时配置为准。
8. 能力边界与免责
- 支持：沪深 A 股 + 港股的历史 K 线查询（日/周/月/分钟级）
- 不支持：实时行情推送、盘中逐笔成交、期货/期权/基金/外汇 K 线、港股 5/30/60 分钟 K 线
- 数据时效：历史数据，非实时；
beginDay不传时返回当天至今的数据，但当天数据可能尚未入库 - 复权限制：分钟级 K 线（5/30/60）不支持
type参数 - 使用合规：商品页声明「数据仅用于学习分析，不得用于对外展示」；将数据嵌入公开产品或提供给终端用户前，请确认是否符合此约束
9. 错误码排查
| HTTP 状态码 | 报头/正文 | 描述 | 排查建议 |
|---|---|---|---|
| 403 | X-Ca-Error-Message: Quota Exhausted |
调用次数用尽 | 检查资源包余量；异步扣量机制下后台余量可能滞后，刷新控制台确认实际余量 |
| 500 | X-Ca-Error-Message: Internal Error |
网关内部错误 | 稍后重试；持续出现时检查网关状态 |
| 555 | 正文 JSON 中解析 | 通常由传参错误引发 | 检查 code 格式、time 值、beginDay 格式（yyyyMMdd）、type 与周期是否匹配 |
200 + showapi_res_code≠0 |
正文含 showapi_res_msg |
业务层错误 | 根据 showapi_res_msg 内容定位具体原因（如无效代码、无数据） |
常见排查步骤
- 确认 AppCode 是否正确、是否在有效期内
- 检查 Query 参数拼写与取值范围
- 港股代码使用 5 位数字（如
00700），A 股使用 6 位数字（如600004） beginDay超过当前日期时返回空列表而非报错- 非交易时段数据更新可能延迟
10. 技术 FAQ
Q：这个接口支持哪些股票？
A：沪深两市 A 股 + 港股。A 股使用 6 位代码，港股使用 5 位代码。
Q：K 线周期怎么选择？
A：5/30/60 为分钟级，适合日内策略回测；day/week/month 为日线及以上，适合中长期分析。港股不支持分钟级。
Q：复权方式有什么区别？
A：bfq 为原始数据（未调整），qfq 以前一日为基准消除分红除息跳空，hfq 以后一日为基准。绘制走势图建议选 qfq。
Q：不传 beginDay 会返回多少数据？
A：默认从当天至今（即返回当天数据），count 字段指示总条数。
Q：数据能用于对外展示吗？
A：不能。商品页明确声明数据仅用于学习分析，不得用于对外展示。对外发布需另寻数据源或使用授权后数据。
Q：调用失败会扣次数吗？
A：不会。只有 HTTP 200 响应才扣减调用次数，非 200 不扣费。
Q：如何批量拉取多只股票？
A：接口为单代码查询，批量需循环调用。建议做并发控制（如 5 线程池），并配合本地缓存降低重复请求。
11. 内容小结
沪深港股历史 K 线数据查询 API 以标准化的 RESTful 接口提供 A 股与港股的日/周/月/分钟级历史行情数据，支持三种复权模式，可直接用于策略回测、教学演示与数据可视化。接入流程清晰：获取 AppCode → 构造 GET 请求 → 解析 JSON → 处理异常。
使用注意事项汇总：
- 港股不支持 5/30/60 分钟 K 线
- 数据仅限学习分析用途，不对外展示
- 非 200 响应不扣次数，403 需检查余量
- 批量场景建议加限流与本地缓存
- 调用地址与 QPS 上限以控制台实时配置为准
本教程基于阿里云云市场「沪深港股历史数据查询分析服务」实际页面数据整理，接口参数与返回结构以商品页在线调试模块为准。
