【A股分钟级高频数据完全手册 #01】Pro版接口体系总览与REST鉴权：42篇地图与从0接入

系列：《A股分钟级高频数据完全手册》｜连载项目 · 纯 GET 取数 · 仅依赖 requests · Pro 版分钟级高频

① 你将得到什么

做高频/分钟级量化，第一步不是写策略，而是先把数据从哪来、怎么稳定取这件事想清楚。A 股的高频数据接口通常按 Pro 版分钟级（含完整历史分时、逐笔、盘口）、普通分时、以及实时源三大家族组织，每族又按市场（沪深/指数/北交所）细分。如果不先建立体系认知，你会陷入每篇都在重复讲鉴权、重复踩频率坑的低效循环。本篇把 42 篇的地图一次性摊开，并给出一套可复用的 REST 鉴权 + 重试退避调用模板------后面 41 篇的技术深入，都是在它的基础上换端点、加加工。

本篇产出：① 42 篇三周期地图（Pro 分钟接入→Pro 技术指标→实时高频+因子回测），知道每个端点取什么、属于哪一族；② 一套稳健的 REST 调用封装（token 鉴权、GET 参数、重试退避、MOCK 演示开关），后面所有篇目直接复用；③ 接口族分类与权限说明（Pro 版需对应权限、普通/实时源的差异）。

读完这篇，你应当能独立把本篇端点数据拉下来、落本地，并跑出一份可用的加工分析表。

② 取数约定

一个端点拉数据，返回里字段名可能中英文混用（不同接口版本、不同数据源习惯不同）。演示用 你的token 占位，代码里 MOCK=True 时回放演示数据，接真实 token 把 MOCK 改成 False 即可，无需改动其他逻辑。

所有请求走 https://api.zhituapi.com + ?token=，纯 GET、仅依赖 requests，不依赖任何付费 SDK。字段口径以接口实际返回为准，本文用 _hit_key 做了大小写/中英文容错；落地前建议先用 print(r[0].keys()) 核对一次你账号下的真实字段名。

落地建议 ：把每天拉到的数据按 代码 + 日期 做主键写入本地 SQLite/CSV，避免重复插入；历史回看靠本地累积，而非反复调接口。本篇示例代码已包含字段容错映射与本地加工函数，你只需把 print 替换为写入语句。

③ 端点分组地图

篇	主接口	内容
01（本篇）	`/hs/pro/latest/{code}.SZ/1/n 等`	体系总览 + REST 鉴权 + 本周期 1--14 地图
02	`/hs/pro/latest/{code}.SZ/1/n`	Pro 版最新 1 分钟分时取数
03	`/hs/pro/history/{code}.SZ/1/n`	Pro 版历史 1 分钟 K 线批量
04	`/hz/pro/latest/fsjy/{code}.SH/1/n`	指数 Pro 版最新分时
05	`/hz/pro/history/fsjy/{code}.SH/1`	指数 Pro 版历史分时
06	`/bj/pro/latest/{code}.BJ/1/n`	北交所 Pro 版最新分时
07	`/bj/pro/history/{code}.BJ/1/n`	北交所 Pro 版历史分时
08	`/hs/latest/{code}.SZ/d/n`	普通最新分时 vs Pro
09	`/hs/history/{code}.SZ/d/n`	普通历史分时
10	`/hs/real/ssjy/{code}`	实时交易（公开源）
11	`/hs/real/time/{code}`	实时交易（券商源）
12	`/hs/real/five/{code}`	买卖五档盘口
13	`/hs/real/zbjy/{code}`	当天逐笔成交
14	`/hs/real/zbjy/{date}/{code}`	历史逐笔成交

本篇涉及字段（落地建表参考）：时间、开、收、高、低、成交量、成交额。

返回结构为 JSON 数组（或含数组字段的对象），每条记录即一根分钟 bar / 一笔明细；字段映射函数已按上述字段做容错映射，直接复用即可。

④ 核心模板函数（自包含·可跑）

python 复制代码

import requests, time, copy
from urllib.parse import quote

BASE = "https://api.zhituapi.com"
# 将 "你的token" 替换成您自己的 token。
TOKEN = "你的token"

# ---------- 字段容错与类型归一 ----------
def _hit_key(d, *cands, default=None):
    """字段容错：接口偶发大小写/中英文混用时，按顺序取第一个非空值"""
    if not isinstance(d, dict):
        return default
    for c in cands:
        if c in d and d[c] not in (None, "", "-", "null"):
            return d[c]
    low = {str(k).lower(): v for k, v in d.items()}
    for c in cands:
        v = low.get(str(c).lower())
        if v not in (None, "", "-", "null"):
            return v
    return default

def _to_float(v, default=None):
    try:
        if v in (None, "", "-", "null", "None"):
            return default
        return float(v)
    except (TypeError, ValueError):
        return default

# ---------- 统一请求：token 鉴权 + 重试退避（MOCK 开关） ----------
MOCK = True
DEMO_DATA = {}

def _get(path, params=None, timeout=10, retries=2, backoff=0.6, default=None):
    """返回 JSON；MOCK=True 时回放 DEMO_DATA；否则真实 GET 并带 token 鉴权、重试 retries 次"""
    if MOCK:
        return copy.deepcopy(DEMO_DATA.get(path, {} if default is None else default))
    q = {"token": TOKEN}
    if params:
        q.update(params)
    last = ""
    for i in range(retries + 1):
        try:
            r = requests.get(BASE + path, params=q, timeout=timeout)
            if r.status_code == 200:
                try:
                    return r.json()
                except ValueError:
                    return default
            last = "HTTP %s %s" % (r.status_code, (r.text or "").strip()[:80])
        except Exception as e:
            last = "%s: %s" % (type(e).__name__, e)
        if i < retries:
            time.sleep(backoff * (i + 1))
    return {"_error": last}


# ---------- 本篇技术深入：稳健 REST 调用模板落地 ----------
# SCAFFOLD 已提供 _hit_key / _to_float / _get(token 鉴权 + 重试退避) / MOCK 开关
def fetch_pro_latest(code="000001.SZ", n=5):
    return _get("/hs/pro/latest/%s/1/%d" % (code, n), default=[])

# 字段解析示例（分钟 K 线典型字段：开高低收/量/额）
def parse_bar(r):
    return {
        "时间": _hit_key(r, "t", "time", "datetime"),
        "开": _to_float(_hit_key(r, "o", "open")),
        "收": _to_float(_hit_key(r, "c", "close")),
        "高": _to_float(_hit_key(r, "h", "high")),
        "低": _to_float(_hit_key(r, "l", "low")),
        "成交量": _to_float(_hit_key(r, "v", "vol", "volume")),
        "成交额": _to_float(_hit_key(r, "a", "amount")),
    }

DEMO_DATA = {
    "/hs/pro/latest/000001.SZ/1/5": [
        {"t":"2024-01-10 09:31:00","o":"10.20","c":"10.25","h":"10.26","l":"10.19","v":"12000","a":"1224000"},
        {"t":"2024-01-10 09:32:00","o":"10.25","c":"10.31","h":"10.33","l":"10.24","v":"15300","a":"1584150"},
        {"t":"2024-01-10 09:33:00","o":"10.31","c":"10.28","h":"10.35","l":"10.26","v":"9800","a":"1007440"},
        {"t":"2024-01-10 09:34:00","o":"10.28","c":"10.34","h":"10.36","l":"10.27","v":"11200","a":"1158080"},
        {"t":"2024-01-10 09:35:00","o":"10.34","c":"10.40","h":"10.42","l":"10.33","v":"17600","a":"1830400"},
    ],
}

def run_check():
    bars = fetch_pro_latest()
    assert isinstance(bars, list) and len(bars) == 5
    p0 = parse_bar(bars[0])
    assert p0["收"] is not None and p0["成交量"] is not None
    assert _hit_key({"Time":"x"}, "t", "time") == "x"
    assert _to_float("10.25") == 10.25 and _to_float("-") is None
    print("校验通过")

if __name__ == "__main__":
    run_check()
    print("-" * 62)
    for b in fetch_pro_latest():
        print(parse_bar(b))

代码讲解 ：① SCAFFOLD 提供字段容错 _hit_key 与带 token 鉴权、重试退避的请求 _get，MOCK 开关让你无需 token 就能验证逻辑；② 本篇导览本周期 14 篇地图（见 §③），并给出当篇技术深入的完整代码（落库 / 因子计算等实质内容，函数命名见代码块）；③ 技术深入代码在本地做加工（如落库去重、因子计算与防未来函数），不消耗接口额度 ；④ run_check() 用断言自检，可放进 CI 持续校验。

⑤ 跑通示例（演示数据）

把上面代码保存为 hf_01.py，MOCK=True 直接跑（Python3 + requests 即可，无需其他依赖）。

预期输出：先打印 校验通过（本篇技术深入的字段容错、取数封装与逻辑自检），随后打印技术深入部分的运行结果（如落库条数 / 因子数组等）。这说明 ①token 鉴权封装可用 ②本篇端点 / 逻辑可跑通 ③关键断言成立。关掉 MOCK、填入真实 token 即可对接生产；把演示写入替换成你的存储即可落地。

⑥ 编号坑

token 是接口唯一鉴权凭证，放在 GET 的 ?token= 参数里；切勿把 token 写进代码仓库或前端，建议从环境变量/配置文件读取后注入。
Pro 版接口需要对应的 Pro 权限（或增值包），普通 token 调 Pro 端点会返回鉴权/权限错误，先确认账号已开通再批量跑。
所有请求都是纯 GET、返回 JSON；不要自己拼 POST 或用 SDK，裸 requests.get 最稳，也最易排查。
频率限制：分钟级/实时接口调用频次有限，批量拉多只票务必加间隔（如 time.sleep），避免触发限流返回空或 403。
字段口径随数据源/版本有差异（时间格式、复权标记、单位），落地前用 print(r $0$ .keys()) 核对一次你账号下的真实字段名。
时间戳时区：行情时间一般为北京时间（UTC+8），做跨日聚合时统一时区，别和服务器本地时区混用。
MOCK 开关：示例代码默认 MOCK=True 回放演示数据，验证逻辑无需 token；接真实数据时改 False 并填 token，其余逻辑不变。
重试退避：网络抖动时 _get 已内置 retries+backoff，生产环境建议 retries=3、backoff=1.0，单接口失败不影响整体 pipeline。

⑦ 小结与下篇预告

体系与鉴权是后面 41 篇的地基：把本篇的调用模板吃透，后面每篇只要替换端点即可。下一篇 #02 我们落地第一个具体端点------用 Pro 版最新 1 分钟分时接口，把个股的分钟 K 线拉下来并解析字段。

本篇是《A股分钟级高频数据完全手册》第 01/42 篇。建议按系列顺序读：主推篇把体系与地基搭好，后面的单点篇（如 #02 起）都是换端点、加加工。

下一篇预告：【A股分钟级高频数据完全手册 #02】Python调用股票1分钟数据接口：Pro版最新分时取数与字段解析

⑧ 免责声明

本文代码仅用于接口调用与本地数据落库的技术演示，所有示例数据均为演示数据（MOCK 开关开启），不构成任何投资建议。股市有风险，入市需谨慎；实盘使用前请在小资金下充分验证接口稳定性与字段口径。