# 数据 API 使用说明：行情与专业研究 一把 API Key 同时获取行情、证券、概念、因子，以及 Alphapai、Gangtise、Jinmen 的研报、会议纪要与点评。本文是统一使用入口，原 `quantdb.md` 地址保持不变。 ## 开始使用 1. 打开 [数据 API 门户](https://8.159.140.83/data/)，使用管理员提供的邀请码注册，保存只显示一次的 Key。 2. 所有接口共用 Base URL：`https://8.159.140.83/data/v1`。 3. 每次带 `X-API-Key: `，或 `Authorization: Bearer `。 原行情专用 Key、研究专用 Key 和对应邀请码已升级为统一数据权限，**密钥字符串不变，无需重新注册或换 Key**。此前已撤销的 Key 不会恢复。统一 Key 可以使用 `/quantdb/*` 与 `/research/*`，不能使用通用数据库查询 `/databases/*`。每位朋友各自注册，独立计量、轮换与撤销；不要多人共用个人 Key。 本文不包含密钥或邀请码。[交互式文档](https://8.159.140.83/data/docs)右上角点 **Authorize**，粘贴一次 Key，即可试调行情和研究接口；`GET /me` 查看实际权限、限额和用量。 ## 先跑通三个请求 在终端设置 `DATA_API_KEY` 为门户领取的 Key，然后执行： ```sh export DATA_API_BASE='https://8.159.140.83/data/v1' # 1. 确认密钥和额度 curl --fail-with-body --max-time 40 -H "X-API-Key: $DATA_API_KEY" "$DATA_API_BASE/me" # 2. 取贵州茅台一天的后复权日线 curl --fail-with-body --max-time 40 -G -H "X-API-Key: $DATA_API_KEY" \ --data-urlencode 'symbol=600519.XSHG' \ --data-urlencode 'start=2026-10-23' --data-urlencode 'end=2026-10-24' \ "$DATA_API_BASE/quantdb/market/t_adj_daily_data" # 3. 找贵州茅台相关研报，返回文档 ID、标题和质量信息 curl --fail-with-body --max-time 40 -G -H "X-API-Key: $DATA_API_KEY" \ --data-urlencode 'ticker=600519.SH' --data-urlencode 'kind=report' \ --data-urlencode 'limit=5' "$DATA_API_BASE/research/documents" ``` 行情接口返回 `rows`；研究列表返回 `documents`。研究列表不带正文，用返回的 `_id` 请求 `/research/documents/{doc_key}` 获取正文。 ## 按需求选接口 以下路径均相对于同一个 Base URL，不需要切换 Key。 | 需求 | 路径 | 最少参数 | |---|---|---| | 权限、限额与用量 | `/me` | 无 | | 行情数据目录与更新时间 | `/quantdb/datasets` | 无 | | A 股后复权日线 | `/quantdb/market/t_adj_daily_data` | start、end；建议同时给 symbol | | A 股分钟线 | `/quantdb/market/t_1m_kline` | start、end；最多 7 天 | | 股票与概念关系 | `/quantdb/concept-mappings` | 可用 as_of 回看历史 | | 全球证券列表 | `/quantdb/securities/list` | 可用 thscode、as_of 筛选 | | 按公司找研报 | `/research/documents` | ticker、kind=report | | 按平台找会议纪要 | `/research/documents` | platform、kind=meeting | | 按平台找点评 | `/research/documents` | platform、kind=opinion（Alphapai / Gangtise） | | 读取一篇正文 | `/research/documents/{doc_key}` | 列表返回的完整 _id | | 获取原件 | `/research/attachments/{doc_key}/{index}` | 详情返回的附件序号 | | 研究数据覆盖与质量规则 | `/research/coverage`、`/research/policy` | coverage 需 platform、stream、since、until | ## Python：同一个客户端取行情和研报全文 只使用 Python 标准库，无需安装 SDK。设置 `DATA_API_KEY` 后直接运行： ```python import json import os from urllib.parse import quote, urlencode from urllib.request import Request, urlopen BASE = "https://8.159.140.83/data/v1" HEADERS = {"X-API-Key": os.environ["DATA_API_KEY"]} def get(path, **params): url = BASE + path + ("?" + urlencode(params) if params else "") with urlopen(Request(url, headers=HEADERS), timeout=40) as response: return json.load(response) bars = get("/quantdb/market/t_adj_daily_data", symbol="600519.XSHG", start="2026-10-23", end="2026-10-24") print("行情：", bars["rows"]) reports = get("/research/documents", ticker="600519.SH", kind="report", limit=5) for report in reports["documents"]: print(report["title"], report["completeness"]) if reports["documents"]: doc_key = quote(reports["documents"][0]["_id"], safe="") document = get("/research/documents/" + doc_key) print(document["content"]["body"]) ``` ## 股票代码与日期 两个数据域保留各自原有代码格式，下面以同一只股票对应说明： | 股票 | 行情 symbol | 研报 ticker / 证券列表 thscode | |---|---|---| | 贵州茅台 | `600519.XSHG` | `600519.SH` | | 平安银行 | `000001.XSHE` | `000001.SZ` | 上面的行情路由为 A 股；证券列表、研究语料和 FactSet 的市场覆盖不同，不能由证券代码存在推断有相应行情。日期区间均左闭右开，例如 start=2026-10-23、end=2026-10-24 只取 10 月 23 日。研究列表的 since / until 按 UTC 和 `time.available_at` 解释，coverage 日期则按对应 stream 的源时区。 ## 行情、证券与因子接口 | 方法与路径 | 用途 | |---|---| | `GET /quantdb/datasets` | 查看快照水位、概念/行业表、行情表、指数、主题、因子、证券和 FactSet 目录 | | `GET /quantdb/concept-mappings` | 按 `as_of` 日期重放同花顺概念变更，读取 PIT 股票-概念关系 | | `GET /quantdb/concepts?table=` | 分页读取最新概念/行业表；表名从 `/quantdb/datasets` 获取 | | `GET /quantdb/market/
` | 读取 A 股行情表；支持 `t_adj_daily_data`、`t_1m_kline`、`t_5m_kline`、`t_30m_kline`、`t_cne5_exposure_data` | | `GET /quantdb/indices/csi-daily` | 中证指数日线历史，支持代码、交易所和日期过滤 | | `GET /quantdb/indices/csi-weights` | 每日中证指数权重，附指数与成分股代码/名称 | | `GET /quantdb/indices/market-weights` | ClickHouse 指数成分权重历史快照，按 index_id 和成分代码查询 | | `GET /quantdb/securities/list` | 同花顺全球证券列表日快照，支持 as_of 和源表代码筛选 | | `GET /quantdb/securities/factset-master` | 规范化 FactSet 上市证券映射，要求 fsym_id、ticker_exchange 或 isin 过滤 | | `GET /quantdb/themes/market` | 通联主题指数行情 | | `GET /quantdb/themes/stock-scores` | 主题关联股票评分 | | `GET /quantdb/themes/hot-rank` | 主题热度排名 | | `GET /quantdb/factors/cne6` | CNE6 日度风格/行业因子暴露 | | `GET /quantdb/forecasts/consensus` | 朝阳永续一致预期快照 | | `GET /quantdb/factset/
` | 分页读取 FactSet 静态快照；筛选参数使用表列名并做精确匹配 | ## 示例 先查看数据集： ```sh curl -H "X-API-Key: $DATA_API_KEY" \ 'https://8.159.140.83/data/v1/quantdb/datasets' ``` 查询某日的股票-概念映射： ```sh curl -G -H "X-API-Key: $DATA_API_KEY" \ --data-urlencode 'as_of=2026-10-24' \ --data-urlencode 'limit=100' \ 'https://8.159.140.83/data/v1/quantdb/concept-mappings' ``` 查询贵州茅台后复权日线。日期区间左闭右开，所以该示例返回 2026-10-20 当日： ```sh curl -G -H "X-API-Key: $DATA_API_KEY" \ --data-urlencode 'start=2026-10-20' \ --data-urlencode 'end=2026-10-21' \ --data-urlencode 'symbol=600519.XSHG' \ --data-urlencode 'limit=100' \ 'https://8.159.140.83/data/v1/quantdb/market/t_adj_daily_data' ``` 查询中证 300 当日日线： ```sh curl -G -H "X-API-Key: $DATA_API_KEY" \ --data-urlencode 'start=2026-10-23' \ --data-urlencode 'end=2026-10-24' \ --data-urlencode 'ticker_symbol=000300' \ --data-urlencode 'exchange=XSHG' \ 'https://8.159.140.83/data/v1/quantdb/indices/csi-daily' ``` 查询 CSI 成分权重和主题评分快照： ```sh curl -G -H "X-API-Key: $DATA_API_KEY" \ --data-urlencode 'as_of=2026-10-23' --data-urlencode 'index_code=000300' \ 'https://8.159.140.83/data/v1/quantdb/indices/csi-weights' curl -G -H "X-API-Key: $DATA_API_KEY" \ --data-urlencode 'as_of=2026-10-23' --data-urlencode 'theme_id=266' \ 'https://8.159.140.83/data/v1/quantdb/themes/stock-scores' ``` 查询沪深300的成分权重和当前全球证券列表： ```sh curl -G -H "X-API-Key: $DATA_API_KEY" \ --data-urlencode 'as_of=2026-10-23' --data-urlencode 'index_code=000300' \ 'https://8.159.140.83/data/v1/quantdb/indices/csi-weights' curl -G -H "X-API-Key: $DATA_API_KEY" \ --data-urlencode 'as_of=2026-10-24' --data-urlencode 'thscode=600519.SH' \ 'https://8.159.140.83/data/v1/quantdb/securities/list' ``` 查询规范化 FactSet 证券映射、CNE6 暴露和一致预期： ```sh curl -G -H "X-API-Key: $DATA_API_KEY" \ --data-urlencode 'isin=CNE000000040' \ 'https://8.159.140.83/data/v1/quantdb/securities/factset-master' curl -G -H "X-API-Key: $DATA_API_KEY" \ --data-urlencode 'as_of=2026-10-23' --data-urlencode 'ticker_symbol=000001' \ 'https://8.159.140.83/data/v1/quantdb/factors/cne6' curl -G -H "X-API-Key: $DATA_API_KEY" \ --data-urlencode 'as_of=2026-10-23' --data-urlencode 'ticker_symbol=000001' \ 'https://8.159.140.83/data/v1/quantdb/forecasts/consensus' ``` 查询 FactSet 证券代码映射： ```sh curl -G -H "X-API-Key: $DATA_API_KEY" \ --data-urlencode 'fsym_id=' \ 'https://8.159.140.83/data/v1/quantdb/factset/sym_v1_sym_ticker_exchange' ``` ## 分页、时间窗和错误 行情类列表响应包含 `rows`、`has_more`、`next_offset` 和 `truncated`。当 `has_more=true` 且 `next_offset` 有值时，将它作为下一页的 `offset`： ```sh curl -G -H "X-API-Key: $DATA_API_KEY" \ --data-urlencode 'limit=100' --data-urlencode 'offset=100' \ 'https://8.159.140.83/data/v1/quantdb/concept-mappings' ``` 每页最多 500 行，偏移最多 1,000,000；达到偏移上限且仍有数据时，响应会将 `truncated` 设为 `true`。可用日期或列筛选继续缩小查询。 - 概念映射：`as_of` 默认为最新概念快照日期，不能晚于该快照日期。 - 日线和 CNE5：日期区间最多 366 天。 - 分钟线：必须提供 `start` 和 `end`，区间最多 7 天。 - CSI 指数日线：数据起始日为 **1990-12-20**，最新日期在 `/quantdb/datasets` 中；单次最多 366 天。 - CSI 权重：当前每日快照覆盖 4 个主要 CSI 指数，已对账到 **2026-10-23**；日快照自 **2026-10-12** 起，`as_of` 选择不晚于该日的最近一份有效快照。`weight` 保留源表百分数值，每个指数约合计 100。 - ClickHouse `t_index_data` 权重：静态快照至 **2026-09-30**；各 `index_id` 的最新日期见 `/quantdb/datasets`，请求晚于该 index 的最新日期会返回 400。`weight` 也是百分点原值。 - 股票列表：每日快照从 **2026-10-15** 起，默认选不晚于 `as_of` 的最近快照，包含上市、退市和预上市记录；可按 `listed_status_code` 过滤。`thscode` 是同花顺格式（如 `600519.SH`），行情接口使用 `.XSHG` / `.XSHE`。 - FactSet 原始和规范化证券主表：快照日期为 **2026-09-08**；原始表查询参数是列名与单个精确匹配值。 - 主题、CNE6 和一致预期：按 `as_of` 选择不晚于该日期的最近一份每日快照。主题相关表中的 `theme_id` 需由同一日期的主题数据/主题主表解析。 - 原共享行情 Key 最多并发 8 个，服务端 QuantDB 查询总并发上限 6；单次默认超时 30 秒，单页响应受 8 MiB 上限约束。 常见状态码：`400` 参数不符合要求；`401` 缺少/无效 Key；`403` Key scope 不允许访问该路由；`429` 用户速率或每日配额已用完；`503` 服务繁忙或数据快照暂不可用；`504` 查询超时。 ## 数据与许可 概念映射、行情和 FactSet 快照从工作区 Parquet 只读查询，数据不会复制到阿里云主机。A 股代码使用 `.XSHG` / `.XSHE` 等交易所后缀。FactSet 与其他供应商数据只能按相应数据许可允许的范围使用和转发。 ## 专业研究接口与质量 当前开放 Alphapai、Gangtise、Jinmen 的 `report`（研报）、`meeting`（会议）、`expert_call`（专家访谈）、`opinion`（点评）。其他研究平台尚未纳入本轮交付验收。 默认只返回 schema v2、live、作品代表、full，排除 restricted / unknown access、标题与图片空壳，以及 font_broken、mojibake、degenerate_text、llm_refusal。部分正文只在 `include_partial=true` 时返回，必须保留并展示 completeness 与 reason。轻度排版、ASR、重复章节和免责声明标记仍可见；full 是系统完整度分类，不代表人工逐篇核实。 原生股票标签尚未全库语义复核，返回 `entity_verification=source_labels_not_semantically_verified`。按 ticker 查询可用于发现候选文档，使用前应阅读正文确认主体关系，不能把标签当成已核验研究对象。 历史数据存在缺口。coverage 的 ok 可能来自官方计数的 85% 阈值或历史基线，不能理解为源站全量一致。数据持续新增、更新，分页不是数据库快照；已修改文档可能跨页移动。 ## 路由 | 路由（相对于统一 Base URL） | 用途 | |---|---| | `GET /research/policy` | 范围、质量策略版本与时间口径 | | `GET /research/documents` | 元数据列表，必须至少提供 platform / kind / ticker / institution 之一 | | `GET /research/documents/{doc_key}` | 元数据与正文；content=false 只返回元数据 | | `GET /research/coverage` | 指定 platform、stream 的日覆盖台账，since 含、until 不含，最多 366 天 | | `GET /research/attachments/{doc_key}/{index}` | 通过相同质量与权限闸门下载本地附件；返回含 SHA-256 的 base64 JSON | 列表参数：`platform, kind, ticker, institution, since, until, limit, cursor, include_partial`。每页最多 500 条，按 `time.available_at` 倒序、同一时刻按 doc_key 升序；将返回的 next_cursor 原样传入下一页。翻页期间保持过滤条件不变，最后一页 next_cursor 为 null。旧版游标不兼容，请从第一页重新开始。 since / until 是 UTC 日期或带时区的 ISO 时间，按 `time.available_at` 过滤，左闭右开。回测使用该字段；published_at 是原文发布钟，不能替代保守可得时间。日期精度与平台延迟余量可能使 available_at 晚于实际抓取，甚至晚于当前时刻。做回测时必须显式传入截止 until。后生成的摘要、翻译与标签还应按生成时间过滤。 正文包含 `body`、`sha256`、`chars` 等 canonical 字段。附件元数据不暴露本地存储路径；download_url 相对于 `/data/`，请与入口拼接。缺文件返回 404，已有原件哈希不符返回 503；历史附件没有保存哈希时返回本次计算的 SHA-256，并明确 `integrity_basis=computed_at_read`，不能视为已核对历史原件。附件最多为服务 JSON 响应上限的一半（默认 4 MiB 文件），超过返回 413。PDF 等二进制解码后使用，不把 base64 字符串作为正文。 ### 研究分页与附件下载 研究列表用 `next_cursor` 翻页：保持其他过滤条件不变，将非空的 next_cursor 原样作为 cursor；为 null 时结束。最多每次 500 篇。不要给研究接口传 offset；行情接口使用 next_offset，两者不能互换。 详情的 `attachments[index].download_url` 相对于 **门户根 `/data/`**，不是 `/data/v1/`；也可直接按 `/research/attachments/{doc_key}/{index}` 请求。下载返回 base64 JSON，用 `base64.b64decode(result["data"])` 还原原件；用返回的 sha256 核对字节。默认文件上限 4 MiB，超过返回 413。不要把 base64 字符串作为正文。 以下示例取 Gangtise 会议和 Alphapai 点评： ```sh curl --fail-with-body --max-time 40 -G -H "X-API-Key: $DATA_API_KEY" \ --data-urlencode 'platform=gangtise' --data-urlencode 'kind=meeting' \ --data-urlencode 'limit=10' "$DATA_API_BASE/research/documents" curl --fail-with-body --max-time 40 -G -H "X-API-Key: $DATA_API_KEY" \ --data-urlencode 'platform=alphapai' --data-urlencode 'kind=opinion' \ --data-urlencode 'limit=10' "$DATA_API_BASE/research/documents" ``` ## 统一额度与错误处理 一把 Key 的行情和研究请求**共用**每分钟、每日次数与字节额度，精确限额以 `/me` 为准。普通个人 Key 默认每分钟 60 次、2 并发、每天 20,000 次 / 2 GiB；原共享行情 Key 的 300 次/分钟、8 并发保持不变，额度由持有人共用。不要把两类接口当成各有一份额度。 单次 JSON 响应默认最多 8 MiB；研究查询预算 15 秒，行情查询 30 秒，行情服务总并发最多 6。研究请求沿用原有质量过滤，统一权限不会放开空壳、损坏正文或通用数据库访问。 | 状态码 | 用户应该做什么 | |---|---| | 400 / 422 | 检查参数、股票代码格式、日期或游标；换了筛选条件须从第一页重取 | | 401 | 检查 Key，可能已被轮换、撤销或账号已停用 | | 403 | 用 `/me` 检查 permissions；统一数据 Key 应同时有 quantdb、research | | 404 | 检查文档 ID；不符合质量规则、非代表副本或文件缺失也会返回 404 | | 413 | 缩小 limit 或返回字段；附件可能超过文件上限 | | 429 | 达到速率、并发或每日额度，降低并发，等额度恢复 | | 503 | 服务繁忙、依赖不可用或完整性校验失败，先读错误消息 | | 504 | 缩小日期区间、增加平台/股票过滤，避免原样重复大查询 | 429 / 临时 503 如需重试，使用带抖动的指数退避，最多 3 次；不要紧密无限重试。每日额度按 UTC 00:00 重置。Key 轮换会立即使旧 Key 失效，更新客户端环境变量即可，接口地址不变。