对接美国股票指数的技术指南

🛠️ 准备工作：获取您的 API 密钥

在开始之前，您需要先获取访问数据的“通行证”——API密钥。

1. 访问官方平台：前往 StockTV 官方网站（pao.stocktv.top）。
2. 申请密钥：通常您需要注册账号并完成开发者资质认证，之后便可以在个人中心或开发者页面找到申请API密钥的选项。
3. 保管密钥：成功获取后，请妥善保管您的 API_KEY。建议通过环境变量等方式进行配置，避免将其直接硬编码在代码中，以确保安全。

基础URL：StockTV API 的服务基础地址为 https://api.stocktv.top。

📡 核心接口详解

以下是几个用于获取美国股票指数数据的核心接口。

1. 获取指数列表接口

在查询具体指数行情前，您可能需要先知道系统中支持哪些美国指数及其对应的ID。

• 接口地址：GET /stock/indices
• 请求示例：

  GET /stock/indices?countryId=1&key=您的API_KEY
  

• 参数说明：
  • countryId: 必填，美国的国家ID为 1。
  • key: 必填，您的API密钥。
• 响应示例：
  该接口会返回一个包含道琼斯指数(.DJI)、标普500指数(.SPX)和纳斯达克指数(.IXIC)等主要指数的列表及其实时行情。

  {
    "code": 200,
    "data": [
      {
        "id": 1,
        "symbol": "DJI",
        "name": "Dow Jones Industrial Average",
        "last": 38750.25,
        "change": 325.50,
        "changePct": 0.85,
        "high": 38820.75,
        "low": 38550.30,
        "time": 1716458537
      }
      // ... 其他指数数据
    ]
  }
  

2. 获取实时行情接口

如果您已经知道特定指数的符号（如.INX代表标普500），可以直接查询其最新价格。

• 接口地址：GET /stock/queryStocks
• 请求示例：

  GET /stock/queryStocks?symbol=.INX&key=您的API_KEY
  

• 参数说明：
  • symbol: 必填，指数的代码，例如 .INX（标普500）, .DJI（道琼斯）。
  • key: 必填，您的API密钥。

3. 获取历史K线数据接口

对于技术分析和图表展示，历史K线数据至关重要。

• 接口地址：GET /stock/kline
• 请求示例：

  GET /stock/kline?pid=指数ID&interval=P1D&key=您的API_KEY
  

• 参数说明：
  • pid: 必填。指数的唯一产品ID，需要从“获取指数列表”接口的响应中获取。
  • interval: 必填。K线的时间周期，常用值如下：
    • PT5M - 5分钟
    • PT1H - 1小时
    • P1D - 1日
    • P1W - 1周
  • key: 必填，您的API密钥。
• 响应示例：

  {
    "code": 200,
    "data": [
      {
        "time": 1725004800000,
        "open": 5230.45,
        "high": 5250.60,
        "low": 5220.10,
        "close": 5241.80,
        "volume": 3301839541
      }
      // ... 更多历史K线数据
    ]
  }
  

💻 实战示例：用 Python 获取并绘制指数K线

以下是一个完整的Python示例，演示如何获取标普500指数的日K线数据并绘制价格走势图。

import requests
import pandas as pd
import matplotlib.pyplot as plt
from datetime import datetime

# 配置请求参数
url = "https://api.stocktv.top/stock/kline"
params = {
    "pid": 2,  # 请替换为实际的标普500指数ID，需通过接口查询
    "interval": "P1D",  # 日线
    "key": "YOUR_API_KEY"  # 替换为你的有效API密钥
}

try:
    # 发送请求
    response = requests.get(url, params=params, timeout=10)
    data = response.json()

    # 检查请求是否成功
    if data.get('code') == 200:
        kline_data = data['data']
        
        # 转换为Pandas DataFrame以便处理
        df = pd.DataFrame(kline_data)
        df['date'] = pd.to_datetime(df['time'], unit='ms')  # 转换时间戳
        df.set_index('date', inplace=True)
        
        # 打印前几行数据
        print("最近5个交易日的K线数据：")
        print(df[['open', 'high', 'low', 'close', 'volume']].head())
        
        # 绘制收盘价走势图
        plt.figure(figsize=(12, 6))
        plt.plot(df.index, df['close'], label='S&P 500 Close Price', color='#2E86AB')
        plt.title('S&P 500 Index Daily Close Price')
        plt.xlabel('Date')
        plt.ylabel('Price')
        plt.legend()
        plt.grid(True, linestyle='--', alpha=0.7)
        plt.show()
        
    else:
        print(f"API请求失败: {data.get('message', 'Unknown error')}")

except requests.exceptions.RequestException as e:
    print(f"网络请求出错: {e}")

🔄 高级功能：WebSocket 实时数据推送

对于需要实时监控指数变动的场景（如量化交易），使用WebSocket比反复轮询API更高效。

• 连接地址：wss://ws-api.stocktv.top/connect?key=您的API_KEY
• 订阅消息：连接建立后，需要发送订阅指令来指定要接收哪些指数的实时数据。

  {
    "action": "subscribe",
    "pids": [1, 2, 3]  // 要订阅的指数ID列表
  }
  

• 心跳机制：为了保持连接，客户端需要每30秒左右向服务器发送一次心跳消息：{"action": "ping"}。

⚠️ 注意事项与最佳实践

1. 频率限制：请注意API的调用频率限制。基础版通常为每分钟100次请求，企业版会更高。超出限制会导致请求失败。
2. 错误处理：在代码中务必检查返回的 code 字段。常见的错误码包括：400（参数错误）、401（API Key无效）、404（数据不存在）等。
3. 性能优化：
   • 批量查询：如需获取多个指数的数据，尽量使用批量查询接口（如 stocksByPids），减少请求次数。
   • 缓存数据：对于公司信息、指数列表等变化不频繁的数据，可以在本地实施缓存策略。
   • 异步处理：对于大量数据请求，考虑使用异步编程来提升效率。

希望这份指南能帮助您顺利对接美国股票指数数据！如果您在具体实践中遇到问题，可以查阅StockTV的官方文档或在技术社区寻求帮助。