> For the complete documentation index, see [llms.txt](https://docscn.jkidata.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docscn.jkidata.com/rest-api-xie-yi-shuo-ming.md).

# REST API协议说明

JKiData REST API 采用标准 HTTP 请求，为开发者提供交易产品、实时报价、历史 K 线及其他金融数据。

本页面仅说明 REST API 的通用调用规则。各接口的请求参数、返回字段和代码示例，请查看对应的接口页面。

### 请求地址

完整请求地址由首页公布的 API 基础地址和接口相对路径组成。

```
{BASE_URL}{PATH}
```

例如：

```
{BASE_URL}/product
{BASE_URL}/quote
{BASE_URL}/bars
```

为便于以后更换服务域名，后续接口页面只展示 `/product`、`/quote`、`/bars` 等相对路径。

### 请求方式

当前 REST API 使用 `GET` 方法，请求参数通过 URL Query String 传递。

```
GET /quote?market=NASDAQ&symbol=AAPL&key=your_api_key
```

请求参数应进行 URL 编码，尤其是名称、关键词或其他包含特殊字符的参数。

### 身份认证

所有请求均需携带有效的 API Key。

| 参数    | 必填 | 说明          |
| ----- | -- | ----------- |
| `key` | 是  | 用户的 API Key |

示例：

```
key=your_api_key
```

API Key 用于身份识别、访问控制和请求额度管理。请勿将正式密钥写入公开代码仓库、前端页面或可公开访问的日志中。

推荐通过服务器环境变量保存密钥：

```
export JKIDATA_API_KEY="your_api_key"
```

### 通用参数

不同接口需要的业务参数不同，常用参数如下。

| 参数         | 说明                             |
| ---------- | ------------------------------ |
| `market`   | 市场或交易所代码，例如 `SZ`、`SH`、`NASDAQ` |
| `symbol`   | 交易产品代码，具体格式取决于所属市场             |
| `key`      | API Key                        |
| `interval` | K 线周期，仅适用于历史 K 线等接口            |
| `page`     | 分页页码，仅适用于支持分页的接口               |

> REST API 请求统一使用 `market` 表示市场或交易所参数，不使用 `exchange` 作为请求参数。

### 当前接口路径

| 接口     | 相对路径       | 主要用途             |
| ------ | ---------- | ---------------- |
| 市场产品列表 | `/product` | 获取指定市场的可用交易产品    |
| 实时报价   | `/quote`   | 获取一个或多个交易产品的最新行情 |
| 历史 K 线 | `/bars`    | 获取指定产品的历史 K 线数据  |

其他数据接口将在对应章节中分别说明。

### 响应格式

不同接口可能返回 JSON 或 CSV 数据。客户端不应假设所有接口使用相同的响应格式。

| 接口         | 数据格式    | 主要内容     |
| ---------- | ------- | -------- |
| `/product` | CSV     | 市场产品列表   |
| `/quote`   | JSON 数组 | 实时报价数据   |
| `/bars`    | CSV     | 历史 K 线数据 |

部分响应的 `Content-Type` 可能显示为：

```
text/plain; charset=UTF-8
```

因此，客户端应结合接口说明和响应正文解析数据，不应仅依赖 `Content-Type` 判断格式。

### JSON 响应

实时报价接口返回 JSON 数组，每个数组元素代表一条行情消息。

结构示例：

```
[
  {
    "type": "quote",
    "msg": {
      "e": "NASDAQ",
      "s": "AAPL",
      "p": 0,
      "utc": 0
    }
  }
]
```

字段含义及不同市场的字段支持情况，请参阅“实时报价字段说明”和 Quote 接口页面。

### CSV 响应

产品列表和历史 K 线接口返回 CSV 文本。

产品列表结构示例：

```
exchange,symbol,name,data type

```

K 线数据结构示例：

```
utc,close,open,high,low,volume
```

解析 CSV 时应注意：

* 第一行为字段名称。
* 字段内容可能包含中文、空值或引号。
* 不建议直接使用逗号分割字符串，应使用标准 CSV 解析器。
* 返回数据统一按照 UTF-8 编码处理。

### 成功与失败判断

客户端不能只根据 HTTP 状态码判断请求是否成功。

部分参数错误、认证失败或业务错误仍可能返回 HTTP `200`，但响应正文中会包含错误状态。因此，客户端应同时检查：

1. HTTP 状态码。
2. 响应正文是否为空。
3. 响应内容属于 JSON 还是 CSV。
4. JSON 中的 `State`、`status` 或其他状态字段。
5. 返回数据是否符合当前接口约定的结构。

### 错误响应

认证失败可能返回类似结构：

```
{
  "Cmd": "api",
  "State": -1,
  "Msg": " NO API Key "
}
```

缺少必填参数时可能返回类似结构：

```
{
  "status": 500,
  "message": "Required request parameter is not present",
  "data": null
}
```

建议将以下情况统一视为请求失败：

* HTTP 状态码不是 `2xx`。
* JSON 中的 `State` 小于 `0`。
* JSON 中的 `status` 表示失败。
* 响应正文为空。
* 返回结构与接口约定不一致。
* CSV 缺少预期的表头。

### 推荐解析流程

```
发送 GET 请求
    ↓
检查 HTTP 状态码
    ↓
读取完整响应正文
    ↓
识别 JSON 或 CSV
    ↓
检查业务状态字段
    ↓
验证返回结构
    ↓
转换为业务数据
```

JSON 响应可以根据首字符进行初步识别：

* `{`：JSON 对象，可能是状态信息或错误信息。
* `[`：JSON 数组，通常为行情数据。
* 其他内容：根据接口约定按 CSV 或文本解析。

### 请求频率与重试

客户端应根据实际业务需求合理控制请求频率。

建议：

* 产品列表可在系统初始化时获取并在本地缓存。
* 实时报价根据业务需要定时请求，较高频场景优先使用 WebSocket。
* 历史 K 线应按页获取，避免短时间重复请求相同数据。
* 网络超时或临时服务错误可进行有限次数重试。
* 参数错误、密钥错误等业务错误不应自动重复请求。

重试时建议采用递增等待时间，避免在服务异常时产生大量重复请求。

### 安全建议

* API Key 应保存在服务端环境变量或密钥管理系统中。
* 不要在公开仓库、网页源码或客户端程序中写入正式密钥。
* 不要在日志中记录包含完整 API Key 的请求地址。
* 测试密钥与生产密钥应分开管理。
* 怀疑密钥泄露时，应及时更换密钥。
* 正式接入时应以首页公布的最新基础地址和传输协议为准。

### 相关文档

* 市场股票列表接口（Product）
* 行情报价接口（Quote）
* K 线数据接口（Bars）
* 市场、国家与语言参数说明
* 实时报价字段说明
* 错误码说明