使用StockTV数据源对接美国股票数据

🎯 核心功能与优势

StockTV API 支持包括美国在内的10多个国家的股票市场数据。其核心优势在于：

• ​​实时数据推送​​：通过 WebSocket 提供毫秒级延迟的实时行情推送。
• ​​数据覆盖面广​​：除了股票，还覆盖指数、外汇、期货和加密货币数据。
• ​​接口标准化​​：提供 RESTful API 和 WebSocket 两种方式，返回统一的 JSON 格式数据，易于集成。

美国市场主要覆盖纽约证券交易所（NYSE）、纳斯达克（NASDAQ）和美国证券交易所（AMEX）等主流交易所。

📋 接入准备

开始之前，你需要完成两项准备：

1. ​​获取API密钥​​：这是访问所有接口的凭证。你需要通过官方指定的方式（例如 Telegram:@stocktvpaopao）联系获取。
2. ​​设置请求基础URL​​：API 的基础地址为 https://api.stocktv.top。对于美国股票数据，部分接口有特定端点，例如 https://api.stocktv.top/us/quote。请在请求头中设置 Content-Type: application/json，并根据接口要求选择在参数中添加 key=YOUR_API_KEY或使用请求头 X-Api-Key: YOUR_API_KEY。

🔧 核心接口详解

以下是几个最常用的美国股票数据接口及其用法。

获取单只股票实时行情

这个接口用于获取指定股票的最新交易数据、基本面指标等。

• ​​接口地址​​：GET /us/quote

• ​​请求参数​​：

  参数	必选	说明	示例值
  symbol	是	股票代码	AAPL

• ​​Python示例代码​​：

  import requests
  
  def get_stock_quote(symbol, api_key):
      url = "https://api.stocktv.top/us/quote"
      params = {"symbol": symbol}
      headers = {
          "X-Api-Key": api_key,  # 或在params中添加：params = {"symbol": symbol, "key": api_key}
          "Content-Type": "application/json"
      }
      response = requests.get(url, params=params, headers=headers)
      if response.status_code == 200:
          data = response.json()
          if data.get("code") == 200:
              return data["data"]
      return None
  
  # 使用示例
  aapl_data = get_stock_quote("AAPL", "YOUR_API_KEY")
  if aapl_data:
      print(f"苹果(AAPL) 最新价: ${aapl_data['price']}")
      print(f"涨跌幅: {aapl_data.get('changePercent', 'N/A')}%")
  

  响应中包含价格、成交量、市值、市盈率等丰富信息。

获取历史K线数据

用于获取股票的历史价格走势，支持不同的时间周期和粒度。

• ​​接口地址​​：GET /us/historical或 GET /stock/kline

• ​​请求参数​​（以/us/historical为例）：

  参数	必选	说明	示例值
  symbol	是	股票代码	AAPL
  period	否	时间周期	1d（1天）, 1m（1个月）, 1y（1年）等
  interval	否	时间粒度	1d（日线）, 1h（1小时）, 5m（5分钟）等
  start	否	开始日期	20240901(YYYYMMDD)
  end	否	结束日期	20240930(YYYYMMDD)

  如果使用 /stock/kline接口，时间间隔参数为 interval，例如 PT1H（1小时）、P1D（日线）。

通过WebSocket订阅实时数据

对于需要低延迟和高频更新的场景（如实时监控、交易系统），WebSocket是更好的选择。

• ​​连接地址​​：wss://ws-api.stocktv.top/us?key=YOUR_API_KEY

• ​​基本步骤​​：

  1. 建立WebSocket连接。
  2. 发送订阅消息，指定关注的股票列表。
  3. 监听服务器推送的实时消息。
  4. 定期发送心跳包（如{"action": "ping"}）以保持连接。

• ​​JavaScript示例代码​​：

  const WebSocket = require('ws');
  const ws = new WebSocket('wss://ws-api.stocktv.top/us?key=YOUR_API_KEY');
  
  ws.on('open', function open() {
      console.log('WebSocket连接已建立');
      // 订阅股票
      const subscribeMsg = {
          action: "subscribe",
          symbols: ["AAPL", "MSFT", "TSLA"]
      };
      ws.send(JSON.stringify(subscribeMsg));
  });
  
  ws.on('message', function incoming(data) {
      const message = JSON.parse(data);
      if (message.symbol) {
          console.log(`实时报价: ${message.symbol} - 价格: ${message.price} | 涨跌: ${message.change} (${message.changePercent}%)`);
      }
  });
  
  // 每30秒发送一次心跳（根据服务器要求）
  setInterval(() => {
      if (ws.readyState === WebSocket.OPEN) {
          ws.send(JSON.stringify({ action: "ping" }));
      }
  }, 30000);
  

  服务器会持续推送包含最新价、涨跌幅、买卖盘等信息的实时数据。

💻 实战应用示例

假设你要构建一个简单的美股监控脚本，可以这样组合使用上述接口：

import requests
import time
from datetime import datetime

class USStockMonitor:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = "https://api.stocktv.top"

    def get_index_overview(self):
        """获取美国主要指数概况（示例，需根据实际接口调整）"""
        # 例如，可能使用 /stock/indices 接口，并指定国家ID（美国为1）
        params = {'countryId': 1, 'key': self.api_key}
        # 发送请求并解析道琼斯、标普500、纳斯达克指数数据
        # ... 具体实现

    def check_stock_alert(self, symbol, price_threshold):
        """检查特定股票价格是否超过阈值"""
        data = get_stock_quote(symbol, self.api_key)
        if data and data['price'] > price_threshold:
            print(f"警报: {symbol} 价格 ${data['price']} 已超过阈值 ${price_threshold}！")
            return True
        return False

# 使用示例
if __name__ == "__main__":
    monitor = USStockMonitor("YOUR_API_KEY")
    while True:
        try:
            monitor.check_stock_alert('AAPL', 180)  # 监控苹果股价是否超过180美元
            time.sleep(60)  # 每分钟检查一次
        except KeyboardInterrupt:
            print("监控已停止。")
            break

⚠️ 注意事项与最佳实践

• ​​频率限制​​：请注意API的调用频率限制。基础版本通常有每分钟100次请求的限制，企业版更高。合理设计请求节奏，避免触发限流。

• ​​错误处理​​：在代码中务必添加完善的错误处理机制，应对网络异常、API限流、数据解析失败等情况。

  try:
      response = requests.get(api_url, params=params, timeout=10)
      response.raise_for_status()  # 检查HTTP状态码
      # ... 处理数据
  except requests.exceptions.RequestException as e:
      print(f"请求出错: {e}")
      # 重试或记录日志
  

• ​​缓存策略​​：对于变化不频繁的数据（如公司基本信息、历史K线），可以考虑在本地进行缓存，以减少不必要的API调用并提升响应速度。

• ​​安全管理API密钥​​：切勿将API密钥直接硬编码在客户端代码或公开的版本库中。建议使用环境变量或安全的配置文件来管理密钥。

希望这份指南能帮助你顺利上手StockTV的美国股票数据接口。如果你在具体实现过程中遇到更细致的问题，比如需要特定技术指标的计算，可以随时提出。