A01_在浏览器地址栏读懂一个行情 REST API 的契约

在浏览器地址栏读懂一个行情 REST API 的契约行情数据本质上是一组 HTTP 接口一个 URL 对应一个资源返回 JSON。本文用「沪深全市场股票列表」这个最小接口演示如何在不装任何 SDK 的情况下仅凭浏览器地址栏把接口契约URL 结构、返回字段、错误模型读明白。所有示例的主机地址都写在代码BASE常量里复制即可运行。1. 为什么从浏览器开始正式写代码之前先用浏览器把接口的「契约」摸清楚能省掉后期大量调试时间URL 怎么拼协议 / 主机 / 路径 / 查询参数正常返回是什么结构数组还是对象、字段名是什么出错返回什么错误码模型浏览器地址栏是一个零成本的「HTTP 客户端」输入 URL 回车看到的文本就是接口的原始响应。后续在 Python / Excel / Java 里做的只是把「人肉回车」换成程序自动发请求。2. 接口契约URL 四段以「沪深全部股票列表」为例请求形如GET /hs/list/all完整地址在代码里给出见下方常量。把它拆成四段理解段示例说明协议https://标准 HTTPS主机api.zhituapi.com接口服务主机见BASE常量路径/hs/list/all资源路径沪深 / 列表 / 全部查询?token...访问凭证路径命名规律/市场/资源/动作。hs沪深、hz指数、hk港股、jh基金list列表类、pool股池类、latest/history行情类。理解这个规律后不必查文档就能推测出大部分接口地址。把完整地址粘进地址栏回车得到[{dm:000001.SZ,mc:平安银行,jys:SZ},{dm:000002.SZ,mc:万 科,jys:SZ},{dm:000006.SZ,mc:深振业,jys:SZ},{dm:000007.SZ,mc:全新好,jys:SZ},{dm:000008.SZ,mc:神州高铁,jys:SZ}]字段含义字段含义dm股票代码带交易所后缀.SZ/.SHmc股票名称jys交易所SZ深圳SH上海返回的是JSON 数组每条一个对象。该接口在 2026-08-11 实测返回5209 条——即当日全市场股票清单。3. 用代码常量承载主机地址关键约定下面所有示例都遵循同一约定把主机地址放进一个BASE常量路径单独拼接。这样换环境、换接口版本只改一处也避免正文里反复出现完整域名。BASEhttps://api.zhituapi.com# 接口主机全文只在此处出现TOKEN你的token# 访问凭证见第 5 节defstock_list_url():returnf{BASE}/hs/list/all?token{TOKEN}print(stock_list_url())# https://api.zhituapi.com/hs/list/all?token你的token后面每个接口都沿用f{BASE}/路径?token{TOKEN}这个模板不再逐条写出完整域名。4. 换几个资源路径试试同一个BASE只改路径就能拿到不同数据资源路径实测条数2026-08-11指数列表/hz/list/hszs611港股列表/hk/list/all3097基金列表/jh/list/all27495涨停股池/hs/pool/ztgc/2026-08-1158涨停股池每条带连板数、封板时间、行业[{dm:000802,mc:北京文化,zf:10.0,p:5.17,cje:254059151,lbc:2,fbt:092500,hy:影视院线}]字段含义zf涨幅%p最新价cje成交额元lbc连板数1首板fbt首封时间HHMMSShy所属行业行情类接口的路径规律/hs/latest/{代码}/{周期}/{复权} # 最新一根 K 线 /hs/history/{代码}/{周期}/{复权} # 历史 K 线周期d日w周m月y年5/15/30/60分钟复权n不复权f前复权b后复权例如/hs/latest/000001/d/f返回平安银行当日前复权日线。返回的 K 线条目形如[{t:2026-08-11,o:11.31,c:11.26,h:11.40,l:11.24,v:663361,a:749686462.02,pc:11.29}]字段含义单位t日期YYYY-MM-DDo开盘价元c收盘价元h/l最高 / 最低价元v成交量手a成交额元pc前收盘价元5. 鉴权与错误模型接口用token做访问凭证。把请求拆开看错误模型比看文档更直观请求HTTP 行为返回文本含义无token400104:缺少token参数URL 没带凭证tokenfaketoken403102:Licence证书(faketoken)不存在凭证无效或过期频率超限401限频提示调用过密需退避几个工程要点错误以纯文本返回不是 JSON。鉴权失败时不返回{...}而是104:.../102:...这种code:msg文本。客户端要先判断响应首字符是否为{再决定走json()还是当作错误解析。token 不要进代码库。生产环境从环境变量读TOKEN os.environ[QUOTE_API_TOKEN]。限频退避。免费档约 300 次/分钟批量循环里加time.sleep(0.2)。如何取得 token返回104说明请求本身正确、只是缺凭证这时按代码里BASE指向的主机地址去其「凭证发放」入口申请一个即可接口契约本身不依赖任何特定厂商。6. 把地址存成书签 一键看数据浏览器书签可以存带参数的完整 URL。把常用接口存成书签点一下就是最新数据书签名地址把 token 换成你的A 股全列表{BASE}/hs/list/all?token你的token指数列表{BASE}/hz/list/hszs?token你的token今日涨停{BASE}/hs/pool/ztgc/2026-08-11?token你的token注意书签里会明文保存 token仅限本机个人使用不要同步到公共账号或提交到仓库。7. 小结行情接口 一组 REST 资源URL 即数据源无需 SDK。URL 四段协议 / 主机代码BASE/ 路径 / 查询。返回 JSON 数组字段为短名dm/mc/jys。错误模型104缺参、102凭证无效、401 限频且以纯文本返回需先判首字符再解析。主机地址只写在代码里换接口只改BASE一处。能在地址栏跑通的请求在任意编程语言里都能跑通。下一篇用requests把这个请求翻译成 Python并加上重试、限频与 DataFrame 落地。本文数据来自公开行情接口实测2026-08-11文中所有接口返回均为真实数据。A 股涨红跌绿不构成任何投资建议。