etf/docs/flask_api_README.md

Universal Data Fetcher API 文档

概述

提供统一的 RESTful API 接口，支持获取各类资产的 K 线数据（OHLCV）。

支持的资产类型

• A股指数: 000300.SH, 399006.SZ, H30269.CSI
• A股ETF: 510300.SH, 159915.SZ, 513100.SH
• A股股票: 600000.SH, 000001.SZ
• 港股指数: HSI, HSTECH.HK
• 美股指数: NDX, SPX, DJI, N225, GDAXI
• 美股股票: AAPL, MSFT, GOOGL, AMZN, TSLA
• 期货合约: AU.SHF, CU.SHF
• 加密货币: BTC, ETH

快速开始

1. 启动服务

# 基础启动（仅支持A股）
./start_flask_server.sh

# 启用 SSH 隧道（支持港美股）
./start_flask_server.sh --with-ssh

# 指定端口
./start_flask_server.sh --port 8080 --with-ssh

# 调试模式
./start_flask_server.sh --debug --with-ssh

2. 测试 API

# 健康检查
curl http://localhost:5000/health

# 获取K线数据
curl 'http://localhost:5000/api/v1/ohlcv?code=000300.SH&start=2024-01-01&end=2024-03-31'

# 批量获取
curl -X POST http://localhost:5000/api/v1/ohlcv/batch \
  -H "Content-Type: application/json" \
  -d '{
    "codes": ["000300.SH", "NDX", "HSI"],
    "start": "2024-01-01",
    "end": "2024-03-31"
  }'

API 端点

1. 健康检查

GET /health

响应:

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00",
  "ssh_configured": true
}

2. 检测资产类型

GET /api/v1/asset-type?code={code}

参数:

• code (required): 标的代码

响应:

{
  "code": "000300.SH",
  "asset_type": "china_index",
  "description": "A股指数"
}

示例:

curl 'http://localhost:5000/api/v1/asset-type?code=000300.SH'
curl 'http://localhost:5000/api/v1/asset-type?code=NDX'
curl 'http://localhost:5000/api/v1/asset-type?code=BTC'

3. 获取K线数据

GET /api/v1/ohlcv?code={code}&start={start}&end={end}&retry={retry}

参数:

• code (required): 标的代码
• start (optional): 开始日期，格式 YYYY-MM-DD，默认90天前
• end (optional): 结束日期，格式 YYYY-MM-DD，默认今天
• retry (optional): 重试次数，默认3

响应:

{
  "code": "000300.SH",
  "asset_type": "china_index",
  "data": [
    {
      "date": "2024-01-02",
      "open": 3538.7244,
      "high": 3542.9624,
      "low": 3502.7866,
      "close": 3502.7866,
      "volume": 128626763.0,
      "code": "000300.SH"
    },
    ...
  ],
  "count": 58,
  "date_range": {
    "start": "2024-01-02",
    "end": "2024-03-29"
  },
  "columns": ["date", "open", "high", "low", "close", "volume", "code"]
}

示例:

# 获取沪深300指数
curl 'http://localhost:5000/api/v1/ohlcv?code=000300.SH&start=2024-01-01&end=2024-03-31'

# 获取纳斯达克100指数（需要SSH隧道）
curl 'http://localhost:5000/api/v1/ohlcv?code=NDX&start=2024-01-01&end=2024-03-31'

# 获取黄金期货
curl 'http://localhost:5000/api/v1/ohlcv?code=AU.SHF&start=2024-01-01&end=2024-03-31'

4. 批量获取K线数据

POST /api/v1/ohlcv/batch

请求体:

{
  "codes": ["000300.SH", "NDX", "HSI"],
  "start": "2024-01-01",
  "end": "2024-03-31",
  "retry": 3
}

响应:

{
  "results": {
    "000300.SH": {
      "code": "000300.SH",
      "asset_type": "china_index",
      "data": [...],
      "count": 58,
      "date_range": {...}
    },
    "NDX": {
      "code": "NDX",
      "asset_type": "us_index",
      "data": [...],
      "count": 61,
      "date_range": {...}
    },
    "HSI": {
      "code": "HSI",
      "asset_type": "hk_index",
      "error": "No data available",
      "data": [],
      "count": 0
    }
  },
  "success_count": 2,
  "failed_count": 1,
  "total": 3,
  "start": "2024-01-01",
  "end": "2024-03-31"
}

示例:

curl -X POST http://localhost:5000/api/v1/ohlcv/batch \
  -H "Content-Type: application/json" \
  -d '{
    "codes": ["000300.SH", "510300.SH", "NDX", "HSI", "AU.SHF"],
    "start": "2024-01-01",
    "end": "2024-03-31"
  }'

5. 获取支持的代码示例

GET /api/v1/supported-codes

响应:

{
  "china_index": {
    "description": "A股指数",
    "examples": ["000300.SH", "399006.SZ", "000016.SH", "H30269.CSI"]
  },
  "china_etf": {
    "description": "A股ETF",
    "examples": ["510300.SH", "159915.SZ", "510500.SH", "513100.SH"]
  },
  ...
}

Python 客户端

安装

pip install requests

使用示例

import requests

# 基础配置
BASE_URL = "http://localhost:5000"

# 1. 健康检查
response = requests.get(f"{BASE_URL}/health")
print(response.json())

# 2. 获取单只标的
def get_ohlcv(code, start, end):
    response = requests.get(
        f"{BASE_URL}/api/v1/ohlcv",
        params={"code": code, "start": start, "end": end}
    )
    return response.json()

# 获取沪深300
data = get_ohlcv("000300.SH", "2024-01-01", "2024-03-31")
print(f"获取到 {data['count']} 条数据")

# 3. 批量获取
def batch_ohlcv(codes, start, end):
    response = requests.post(
        f"{BASE_URL}/api/v1/ohlcv/batch",
        json={"codes": codes, "start": start, "end": end}
    )
    return response.json()

# 批量获取
results = batch_ohlcv(
    ["000300.SH", "NDX", "HSI"],
    "2024-01-01",
    "2024-03-31"
)

for code, result in results['results'].items():
    if 'error' not in result:
        print(f"✓ {code}: {result['count']} 条")
    else:
        print(f"✗ {code}: {result['error']}")

错误处理

错误响应格式

{
  "error": "错误描述",
  "code": "000300.SH",
  "start": "2024-01-01",
  "end": "2024-03-31"
}

常见错误码

HTTP 状态码	说明	解决方案
400	参数错误	检查请求参数格式
404	数据不存在	检查代码是否正确，日期范围是否合理
500	服务器内部错误	查看服务器日志

常见错误

1. 代码不存在

{
  "error": "No data available for the specified code and date range",
  "code": "INVALID",
  "start": "2024-01-01",
  "end": "2024-03-31"
}

2. 日期格式错误

{
  "error": "Invalid date format. Use YYYY-MM-DD",
  "start": "2024-01-01",
  "end": "2024/03/31"
}

3. 缺少必需参数

{
  "error": "Missing required parameter: code",
  "example": "/api/v1/ohlcv?code=000300.SH&start=2024-01-01&end=2024-03-31"
}

环境配置

必需环境变量

# Tushare Token（获取A股数据必需）
export TUSHARE_TOKEN=your_token_here

可选环境变量（SSH隧道）

# 启用 SSH 隧道（支持港美股）
export SSH_ENABLED=true
export SSH_HOST=8.218.167.69
export SSH_PORT=22
export SSH_USERNAME=root
export SSH_KEY_PATH=hk_ecs.pem
export SSH_LOCAL_PORT=1080

.env 文件示例

# Tushare
TUSHARE_TOKEN=your_tushare_token_here

# SSH 隧道（可选）
SSH_ENABLED=true
SSH_HOST=8.218.167.69
SSH_PORT=22
SSH_USERNAME=root
SSH_KEY_PATH=hk_ecs.pem
SSH_LOCAL_PORT=1080

性能说明

响应时间

• A股数据: ~500ms/只
• 港美股数据: ~1-2s/只（通过SSH隧道）
• 批量获取: 并发处理，总体时间取决于最慢的数据源

限流说明

• Tushare: 受 API 频率限制
• YFinance: 建议添加延迟避免限流
• 批量获取: 自动添加 0.5s 延迟

注意事项

1. SSH 隧道: 获取港美股数据需要配置 SSH 隧道
2. Tushare Token: 获取A股数据需要有效的 Tushare Token
3. 日期范围: 建议单次查询不超过 1 年数据
4. 网络环境: 中国大陆直接访问 YFinance 可能受限

示例代码

查看完整示例:

• Python 客户端
• API 测试

更新日志

v1.0.0 (2024-XX-XX)

• 初始版本
• 支持8种资产类型
• RESTful API 接口
• Python 客户端
• SSH 隧道支持