python_market_data_service/API_KLINE_RESPONSE.md

# 股票K线接口响应数据说明

## 接口信息

**接口地址**: `GET /v1/stock/klines/{symbol}`

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| symbol | string | 是 | 标的代码，如 000001.SZ |
| start | string | 是 | 开始日期，格式 YYYYMMDD |
| end | string | 是 | 结束日期，格式 YYYYMMDD |
| freq | string | 否 | 周期，默认 1d (1m/5m/15m/30m/60m/1d/1w/1M) |
| adjust | string | 否 | 复权类型，默认空 (qfq/hfq) |

**请求头**:
```
X-API-Key: your_api_key
```

---

## 响应数据结构

### 顶层结构

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "symbol": "000001.SZ",
    "name": "平安银行",
    "freq": "1d",
    "adjust": "NONE",
    "count": 10,
    "items": [
      // K线数据项数组
    ]
  }
}
```

### K线数据项 (items)

每个 K 线数据项包含以下字段：

#### 基础字段

| 字段名 | 类型 | 说明 | 示例 |
|--------|------|------|------|
| symbol | string | 标的代码 | "000001.SZ" |
| time | string (ISO8601) | 时间戳 | "2026-03-01T00:00:00" |
| open | number | 开盘价 | 10.5 |
| high | number | 最高价 | 11.2 |
| low | number | 最低价 | 10.3 |
| close | number | 收盘价 | 10.8 |
| volume | integer | 成交量(股) | 100000 |
| amount | number | 成交金额(元) | 1080000 |

#### 扩展字段

| 字段名 | 类型 | 说明 | 示例 |
|--------|------|------|------|
| trade_date | string | 交易日 (YYYY-MM-DD) | "2026-03-01" |
| is_limit_up | boolean | 是否涨停 | false |
| is_limit_down | boolean | 是否跌停 | false |
| total_market_cap | number | 总市值(元) | 1500000000 |
| float_market_cap | number | 流通市值(元) | 1200000000 |
| inst_holding_ratio | number | 机构持仓占比(%) | 25.5 |
| trading_days | integer | 可交易日数(从上市至今) | 5000 |
| created_at | string (ISO8601) | 数据创建时间 | "2026-03-01T12:00:00" |

---

## 完整响应示例

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "symbol": "000001.SZ",
    "freq": "1d",
    "adjust": "NONE",
    "count": 2,
    "items": [
      {
        "symbol": "000001.SZ",
        "time": "2026-03-01T00:00:00",
        "open": 10.5,
        "high": 11.2,
        "low": 10.3,
        "close": 10.8,
        "volume": 100000,
        "amount": 1080000,
        "trade_date": "2026-03-01",
        "is_limit_up": false,
        "is_limit_down": false,
        "total_market_cap": 1500000000,
        "float_market_cap": 1200000000,
        "inst_holding_ratio": 25.5,
        "trading_days": 5000,
        "created_at": "2026-03-01T12:00:00"
      },
      {
        "symbol": "000001.SZ",
        "time": "2026-03-02T00:00:00",
        "open": 10.8,
        "high": 11.5,
        "low": 10.6,
        "close": 11.2,
        "volume": 120000,
        "amount": 1344000,
        "trade_date": "2026-03-02",
        "is_limit_up": true,
        "is_limit_down": false,
        "total_market_cap": 1550000000,
        "float_market_cap": 1240000000,
        "inst_holding_ratio": 25.6,
        "trading_days": 5001,
        "created_at": "2026-03-02T12:00:00"
      }
    ]
  }
}
```

---

## 字段说明

### 涨停跌停判断

- **is_limit_up**: 当日是否涨停（收盘价 >= 涨停价）
- **is_limit_down**: 当日是否跌停（收盘价 <= 跌停价）

### 市值数据

- **total_market_cap**: 总市值 = 收盘价 × 总股本
- **float_market_cap**: 流通市值 = 收盘价 × 流通股本

### 机构持仓

- **inst_holding_ratio**: 机构持仓占比，表示机构投资者持有该股票的比例

### 交易日期

- **trade_date**: 格式为 "YYYY-MM-DD"，方便前端展示
- **trading_days**: 从上市至今的可交易日数

---

## 测试脚本

使用以下命令测试接口：

```bash
python test_klines_api.py
```

或直接 curl：

```bash
curl -X GET "http://localhost:8080/v1/stock/klines/000001.SZ?start=20260301&end=20260310&freq=1d" \
  -H "X-API-Key: demo-api-key-2024"
```