HTTP API 调用说明

QuantSource API 使用 HTTP GET 提供财经数据查询，基础地址为 https://quantsource.cc。首次接入可以先按快速开始完成一次请求。

用途	地址
用户手册	`https://quantsource.cc/docs/`
API 首页	`https://quantsource.cc/api/`
Swagger 在线调试	`https://quantsource.cc/api/docs`
ReDoc 接口参考	`https://quantsource.cc/api/redoc`
OpenAPI 定义	`https://quantsource.cc/api/openapi.json`
公开数据接口	`https://quantsource.cc/api/public/{item_id}`

查找接口和参数

/api/docs：Swagger 文档，可搜索接口名、查看参数类型和默认值，并使用 Try it out 发送请求。
/api/openapi.json：供客户端工具读取的 OpenAPI 定义。

在 /api/docs 中搜索 stock_zh_a_hist，打开 GET /api/public/stock_zh_a_hist，即可查看该接口的参数。 item_id 表示 QuantSource 的函数名，例如 stock_zh_a_hist。动态路径 /api/public/{item_id} 的接口名下拉框列出服务已注册的接口；查看参数时，请打开对应接口单独生成的文档条目。

HTTP 接口的可调用列表与参数以在线 Swagger / OpenAPI 为准。接口出现在文档中表示已注册，实际是否返回数据还取决于参数、数据源和网络状态。按类别查找和理解字段的方法见查找和理解接口。

请求一只股票的历史数据

请求地址：

https://quantsource.cc/api/public/stock_zh_a_hist?symbol=000001&period=daily&start_date=20240101&end_date=20240131&adjust=&timeout=10

路径末尾的 stock_zh_a_hist 选择接口；? 后是参数，参数之间用 & 分隔。 symbol=000001 指定股票，period=daily 指定日线。

该接口的参数如下：

参数	类型	默认值	含义
`symbol`	字符串	`000001`	股票代码，保留前导零
`period`	字符串	`daily`	周期：`daily`、`weekly`、`monthly`
`start_date`	字符串	`19700101`	`YYYYMMDD` 格式的有效开始日期，例如 `20240101`
`end_date`	字符串	`20500101`	`YYYYMMDD` 格式的有效结束日期，不能早于开始日期
`adjust`	字符串	空字符串	空字符串为不复权；`qfq` 为前复权，`hfq` 为后复权
`timeout`	数字	`None`	QuantSource 请求上游数据源的超时秒数；必须为有限的正数，可省略
`cookie`	字符串	`None`	可选的上游浏览器会话 Cookie；通常可省略

该接口所有参数都有默认值，可以只发送 ?symbol=000001。要查询另一只股票，修改 symbol；要限制日期范围，传入 start_date 和 end_date。adjust= 表示显式传入空字符串。

HTTP 查询参数在网络上是文本。服务按照函数支持的类型声明进行转换，例如 timeout=10 转换为浮点数，字符串类型的 symbol=000001 保持不变。省略 timeout 时使用原函数的 None 默认值；不要发送 timeout=None，因为字符串 None 不是有效数字。

stock_zh_a_hist 的 period 和 adjust 在 Swagger 中显示为下拉选项，服务也会校验这些选项。日期除了检查八位数字格式，还会检查实际存在的日历日期，例如 20240229 有效，20230229 和 20240230 无效。起止日期相同可以查询当天；起止顺序检查会包含被省略参数的默认值。 timeout=0、负数、nan 和 inf 均返回 422。

Python 客户端

import requests

url = "https://quantsource.cc/api/public/stock_zh_a_hist"
params = {
    "symbol": "000001",
    "period": "daily",
    "start_date": "20240101",
    "end_date": "20240131",
    "adjust": "",
    "timeout": 10,
}

response = requests.get(url, params=params, timeout=30)
if not response.ok:
    print(response.status_code, response.json())
response.raise_for_status()
data = response.json()
print(data)

params=params 让 requests 把字典编码成 URL 查询字符串，编码后的请求与直接访问上面的地址相同。params 中的 timeout=10 传给服务端的数据接口， requests.get(..., timeout=30) 则设置客户端自身的等待超时。

curl 客户端

以下命令适用于 Bash；Windows PowerShell 可以使用 curl.exe 并将参数写在一行。

curl --get "https://quantsource.cc/api/public/stock_zh_a_hist" \
  --data-urlencode "symbol=000001" \
  --data-urlencode "period=daily" \
  --data-urlencode "start_date=20240101" \
  --data-urlencode "end_date=20240131" \
  --data-urlencode "adjust=" \
  --data-urlencode "timeout=10"

使用客户端的查询参数编码功能可以正确保留中文、空格，以及参数值中的 &、=、+ 和引号。手写 URL 时也需要对这些字符进行 URL 编码。

参数校验和错误响应

公开接口和兼容保留的 /api/private/{item_id} 使用相同的参数定义：

参数名必须是函数支持的命名参数，拼写错误会返回 422。
没有默认值的参数必须提供；省略有默认值的参数时，由原函数提供默认值。
按支持的类型声明校验字符串、整数、浮点数、布尔值和集合。 Literal 声明的选项也会校验；无法作为查询字段表示的类型使用字符串。
集合参数可以使用重复键，例如 symbols=000001&symbols=000002；单值参数如 symbol 重复出现会返回 422。
参数作为数据传给函数，不会被拼接成 Python 代码执行。

通用校验依据函数签名。stock_zh_a_hist 额外校验周期、复权选项、有效日期、起止日期顺序和正数超时。这些检查在调用数据源之前完成。股票是否存在、是否有交易数据等仍由数据源决定；其他接口的业务规则仍由具体 QuantSource 接口处理。

HTTP 状态码	含义	处理方式
`200`	调用成功	读取 JSON；DataFrame 返回记录数组，空表可能返回 `[]`
`501`	私有接口尚未开放	使用当前可用的公开接口
`404`	路径不存在或接口返回 `None`	检查路径和接口的返回行为
`422`	参数名、必填项、支持的类型或已配置的业务规则不符合要求；动态接口名也可能无效	根据错误中的参数位置修改请求
`502`	上游调用、数据解析或接口参数定义失败	核对接口要求，稍后重试；持续失败时记录请求信息并反馈

多余参数的响应示例：

{
  "error": "接口 stock_zh_a_hist 不支持参数: surprise",
  "interface": "stock_zh_a_hist"
}

缺失参数或类型错误的响应包含 detail 数组，其中 loc 指明出错位置，例如 ["query", "timeout"]。生成的公开路由可能直接返回 FastAPI 的 {"detail": [...]}，动态路由还包含 error 和 interface。客户端应先检查 HTTP 状态码，再读取错误信息。

日期顺序错误的响应示例：

{
  "error": "参数错误",
  "interface": "stock_zh_a_hist",
  "detail": [
    {
      "loc": ["query", "end_date"],
      "msg": "结束日期不能早于开始日期",
      "type": "value_error.date_order"
    }
  ]
}