# HTTP API 调用说明

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

| 用途 | 地址 |
| --- | --- |
| 用户手册 | `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/redoc`：ReDoc 分类目录，选择数据类别后阅读接口参考。
- `/api/openapi.json`：供客户端工具读取的完整 OpenAPI 定义。
- `/api/openapi/{category}.json`：单个类别的 OpenAPI 定义，例如股票类为
  `/api/openapi/stock.json`，基金类为 `/api/openapi/fund.json`。

在 `/api/docs` 选择“股票”（或直接打开 `/api/docs?category=stock`），筛选 `stock_zh_a_hist`，打开
`GET /api/public/stock_zh_a_hist`，即可查看该接口的参数。
ReDoc 可直接打开 `/api/redoc?category=stock`。页面顶部可切换类别，或在
ReDoc 与 Swagger 之间切换并保留所选类别。两种文档每次只加载所选类别。

`item_id` 表示 QuantSource 的函数名，例如 `stock_zh_a_hist`。在“服务与通用接口”类别中，动态路径
`/api/public/{item_id}` 的接口名下拉框列出服务已注册的接口；查看参数时，
请打开对应接口单独生成的文档条目。

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

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

请求地址：

```text
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 客户端

```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` 并将参数写在一行。

```bash
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` | 上游调用、数据解析或接口参数定义失败 | 核对接口要求，稍后重试；持续失败时记录请求信息并反馈 |

多余参数的响应示例：

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

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

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

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