# 快速开始

QuantSource API 使用 HTTP GET 查询财经数据，基础地址为 `https://quantsource.cc`。准备一个 HTTP 客户端即可调用，例如浏览器、curl 或 Python requests。

## 1. 找到接口

在 [数据接口目录](../data/index.rst) 中按类别查找，或打开 [Swagger](https://quantsource.cc/api/docs) 搜索接口名。以 A 股历史行情为例，接口名为 `stock_zh_a_hist`，路径为：

```text
GET /api/public/stock_zh_a_hist
```

每个接口的参数和返回字段不同，填写前请先阅读对应接口说明。完整流程见 [查找和理解接口](../guides/find-interface.md)。

## 2. 发起查询

下面查询股票 `000001` 在指定日期范围内的日线，不做复权：

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

也可以使用 Python：

```python
import requests

response = requests.get(
    "https://quantsource.cc/api/public/stock_zh_a_hist",
    params={
        "symbol": "000001",
        "period": "daily",
        "start_date": "20240101",
        "end_date": "20240131",
        "adjust": "",
        "timeout": 10,
    },
    timeout=30,
)
response.raise_for_status()
rows = response.json()
print(rows)
```

需要使用 Python 示例时，在你的客户端环境安装 `requests` 即可，无需安装 QuantSource 服务端。股票代码使用字符串，以保留前导零。

## 3. 读取结果

表格数据通常返回 JSON 记录数组，每条记录的字段以接口文档中的“输出参数”为准。空表可能返回 `[]`；部分接口返回其他 JSON 类型，应按其说明处理。

先检查 HTTP 状态码，再解析响应。参数无效通常返回 `422`，上游数据获取或解析失败可能返回 `502`。错误中如包含 `request_id`，反馈问题时一并提供，便于定位。

## 接口与调用范围

当前可调用接口使用 `/api/public/{item_id}`，无需附加尚未提供的 API Key。`/api/private/*` 尚未开放，调用会返回 `501`；不要将其作为已可用的认证接口。

数据覆盖、更新频率、复权方式和单位以各接口说明及数据源为准。出现空结果或异常数据时，请先核对日期、参数和数据源覆盖范围。详细的编码规则、参数类型、Python / curl 示例及错误说明见 [HTTP API 调用说明](../reference/http-api.md)。