系列：《零依赖量化数据实战》｜零依赖 · 纯 GET · 不 import 任何 SDK
适用：想用 Python 把港股的财务三表（利润/营收/现金流）、业绩报表与预告、以及机构/基金/社保/券商持股一次拉齐的量化爱好者；数据由智兔数服提供，不依赖任何行情终端。

1. 你将得到什么

• 19 个官方接口的最小可用封装，分三组：
• 港股财务三表与业绩（/hicw，9）：yl 盈利、yy 营收、cz 出资、cznl 出资能力、xj 现金、yjbb 业绩报表、yjyg 业绩预告、yjkb 业绩快报（这 8 个带 {年度}/{季度} 路径参数），lr 利润（无参）。
• 港股利润结构（/higg，6）：jlr 净利润、jlrl 净利润率、zljlr 主力净利润、zljlrl 主力净利润率、shzlr 散户净利润、shjlrl 散户净利润率（均无参）。
• 港股机构持股（/hijg，4）：jgcghz 机构持股汇总、jj 基金持股、sb 社保持股、qf 券商持股（带 {年度}/{季度} 路径参数）。
• 一个对字段名不敏感的排名函数 rank_by：按候选键（如 净利润/jlr/net_profit）降序取前 N。

2. 端点语义表

GET https://api.zhituapi.com/hicw/yl/2020/1?token=你的智兔token      -> 盈利（利润表）
GET https://api.zhituapi.com/hicw/yy/2020/1?token=你的智兔token      -> 营收
GET https://api.zhituapi.com/hicw/cz/2020/1?token=你的智兔token      -> 出资
GET https://api.zhituapi.com/hicw/cznl/2020/1?token=你的智兔token    -> 出资能力
GET https://api.zhituapi.com/hicw/xj/2020/1?token=你的智兔token      -> 现金流
GET https://api.zhituapi.com/hicw/yjbb/2020/1?token=你的智兔token    -> 业绩报表
GET https://api.zhituapi.com/hicw/yjyg/2020/1?token=你的智兔token    -> 业绩预告
GET https://api.zhituapi.com/hicw/yjkb/2020/1?token=你的智兔token    -> 业绩快报
GET https://api.zhituapi.com/hicw/lr?token=你的智兔token             -> 利润（无参）

GET https://api.zhituapi.com/higg/jlr?token=你的智兔token            -> 净利润
GET https://api.zhituapi.com/higg/jlrl?token=你的智兔token           -> 净利润率
GET https://api.zhituapi.com/higg/zljlr?token=你的智兔token          -> 主力净利润
GET https://api.zhituapi.com/higg/zljlrl?token=你的智兔token         -> 主力净利润率
GET https://api.zhituapi.com/higg/shzlr?token=你的智兔token          -> 散户净利润
GET https://api.zhituapi.com/higg/shjlrl?token=你的智兔token         -> 散户净利润率

GET https://api.zhituapi.com/hijg/jgcghz/2020/1?token=你的智兔token  -> 机构持股汇总
GET https://api.zhituapi.com/hijg/jj/2020/1?token=你的智兔token      -> 基金持股
GET https://api.zhituapi.com/hijg/sb/2020/1?token=你的智兔token      -> 社保持股
GET https://api.zhituapi.com/hijg/qf/2020/1?token=你的智兔token      -> 券商持股

鉴权：token 走查询参数；/hicw/ 与 /hijg/ 的 {年度}/{季度} 是路径参数（如 2020/1），不是查询参数。数据来自 智兔数服（www.zhituapi.com）。

3. 字段名不固定？用候选键命中

港股财务返回的「净利润」可能叫 净利润 / jlr / net_profit。统一候选键命中：

def _hit_key(d, keys):
    if not isinstance(d, dict):
        return None
    for k in keys:
        if k in d and d[k] is not None:
            return d[k]
    low = {str(x).lower(): x for x in d.keys()}
    for k in keys:
        kl = k.lower()
        if kl in low:
            return d[low[kl]]
    return None

4. 核心模板函数

import sys, requests

BASE = "https://api.zhituapi.com"
TOKEN = "你的智兔token"  # 占位，换成你申请的真实 token

def _hit_key(d, keys):
    if not isinstance(d, dict):
        return None
    for k in keys:
        if k in d and d[k] is not None:
            return d[k]
    low = {str(x).lower(): x for x in d.keys()}
    for k in keys:
        kl = k.lower()
        if kl in low:
            return d[low[kl]]
    return None

def _to_float(v):
    try:
        return None if v is None else float(v)
    except (TypeError, ValueError):
        return None

def _get(path, params=None):
    p = dict(params or {})
    p["token"] = TOKEN
    try:
        r = requests.get(f"{BASE}{path}", params=p, timeout=10)
    except Exception as e:
        return None, f"网络异常：{e}"
    if r.status_code != 200:
        return None, f"{r.status_code} {r.text.strip()[:140]}"
    try:
        return r.json(), None
    except Exception:
        return None, f"非 JSON：{r.text.strip()[:140]}"

# 港股财务三表与业绩（/hicw，后 8 个带 {年度}/{季度}，lr 无参）
def fetch_cw(sub, year=None, quarter=None):
    if sub == "lr":
        return _get("/hicw/lr")
    return _get(f"/hicw/{sub}/{year}/{quarter}")

# 港股利润结构（/higg，6 个，无参）
def fetch_higg(kind):
    return _get(f"/higg/{kind}")

# 港股机构持股（/hijg，4 个，带 {年度}/{季度}）
def fetch_holder(sub, year, quarter):
    return _get(f"/hijg/{sub}/{year}/{quarter}")

def rank_by(rows, keys, descending=True, topn=None):
    if not isinstance(rows, list):
        return rows
    def sc(x):
        return _to_float(_hit_key(x, keys)) or 0.0
    out = sorted(rows, key=sc, reverse=descending)
    return out[:topn] if topn else out

def selftest():
    # 合成数据仅逻辑自验，非真实行情
    rows = [
        {"code": "H1", "净利润": 120.0},
        {"code": "H2", "jlr": 80.0},
        {"code": "H3", "net_profit": 200.0},
    ]
    top = rank_by(rows, ["净利润", "jlr", "net_profit"], topn=2)
    assert [x["code"] for x in top] == ["H3", "H1"], top
    for sub in ("yl", "yy", "cz", "cznl", "xj", "yjbb", "yjyg", "yjkb", "lr"):
        assert sub in ("yl", "yy", "cz", "cznl", "xj", "yjbb", "yjyg", "yjkb", "lr")
    for sub in ("jgcghz", "jj", "sb", "qf"):
        assert sub in ("jgcghz", "jj", "sb", "qf")
    print("selftest PASS")

if __name__ == "__main__":
    if len(sys.argv) > 1 and sys.argv[1] == "--selftest":
        selftest()
    else:
        for sub in ("yl", "yy", "cz", "cznl", "xj", "yjbb", "yjyg", "yjkb"):
            print(f"cw.{sub} ->", fetch_cw(sub, 2020, 1))
        print("cw.lr ->", fetch_cw("lr"))
        for kind in ("jlr", "jlrl", "zljlr", "zljlrl", "shzlr", "shjlrl"):
            print(f"higg.{kind} ->", fetch_higg(kind))
        for sub in ("jgcghz", "jj", "sb", "qf"):
            print(f"holder.{sub} ->", fetch_holder(sub, 2020, 1))

5. 代码自验结果

离线 selftest（合成数据，仅验证逻辑，不含任何真实行情）：

selftest PASS

联网实测（占位 token，真实返回）：

--- 联网实测（占位 token，预期 404 102:Licence证书不存在）---
cw.yl -> (None, '404 102:Licence证书(你的智兔token)不存在')
cw.yy -> (None, '404 102:Licence证书(你的智兔token)不存在')
cw.cz -> (None, '404 102:Licence证书(你的智兔token)不存在')
cw.cznl -> (None, '404 102:Licence证书(你的智兔token)不存在')
cw.xj -> (None, '404 102:Licence证书(你的智兔token)不存在')
cw.yjbb -> (None, '404 102:Licence证书(你的智兔token)不存在')
cw.yjyg -> (None, '404 102:Licence证书(你的智兔token)不存在')
cw.yjkb -> (None, '404 102:Licence证书(你的智兔token)不存在')
cw.lr -> (None, '404 102:Licence证书(你的智兔token)不存在')
higg.jlr -> (None, '404 102:Licence证书(你的智兔token)不存在')
higg.jlrl -> (None, '404 102:Licence证书(你的智兔token)不存在')
higg.zljlr -> (None, '404 102:Licence证书(你的智兔token)不存在')
higg.zljlrl -> (None, '404 102:Licence证书(你的智兔token)不存在')
higg.shzlr -> (None, '404 102:Licence证书(你的智兔token)不存在')
higg.shjlrl -> (None, '404 102:Licence证书(你的智兔token)不存在')
holder.jgcghz -> (None, '404 102:Licence证书(你的智兔token)不存在')
holder.jj -> (None, '404 102:Licence证书(你的智兔token)不存在')
holder.sb -> (None, '404 102:Licence证书(你的智兔token)不存在')
holder.qf -> (None, '404 102:Licence证书(你的智兔token)不存在')

把 TOKEN = "你的智兔token" 换成你申请的真实 token，上述函数即可打印港股财务三表、业绩与机构持股数据。本文未编造任何真实数值。

6. 坑与注意事项

1. 102 不代表路径对：404 102 是「证书不存在」（鉴权先于路由），路径合法与否要靠客户端白名单自查。
2. {年度}/{季度} 是路径参数：/hicw/* 与 /hijg/* 的 年度、季度 拼在路径里（如 2020/1），季度通常取 1~4，不要写成查询参数。
3. 港股 ≠ 沪深：这些是 hicw/higg/hijg 港股端点，与 /hs/（沪深）字段和市场不同，调用时别混。
4. 利润结构无参：/higg/* 与 /hicw/lr 不带 年度/季度，直接 ?token；其余 /hicw/*、/hijg/* 必带。
5. 字段名中英文混用：「净利润」可能叫 净利润/jlr/net_profit，务必候选键命中。

7. 小结与下篇预告

本篇把「港股财务三表 + 业绩 + 机构持股」拧成了 19 个零依赖接口的最小封装，重点解决了年度/季度 路径参数、港股与沪深市场区分、利润结构有无参数两种形态三个坑，配 rank_by 候选键排名即可一行出榜。

下一篇计划写 #30《沪深板块与股票列表》：讲解如何用官方接口拉取沪深板块分类（/hs/list/sectors、/hs/sectors）与新股/主板/创业板列表（/hs/list/new、/hs/list/primary）数据。

8. 免责声明

本文仅演示公开数据接口的用法，所有代码示例均以占位 token 自验，未含任何真实数据；文中合成数据仅为逻辑自验用途，不构成投资建议，亦不承诺收益。

免费领取证书
数据来自 智兔数服（www.zhituapi.com）：零 SDK、纯 GET、免费版即可起步。

领取路径：进入 www.zhituapi.com → 点击「请求证书」→「证书获取」→「免费版」（邮箱验证 3 步即可拿到 token）。

把代码里的 你的智兔token 换成你拿到的真实 token，上面的脚本就能直接打印港股财务三表、业绩与机构持股数据。