美股市场API技术对接指南，涵盖实时行情、历史数据、指数信息、公司详情等功能

一、概述

StockTV API为开发者提供全面的美股市场数据接口，涵盖实时行情、历史数据、指数信息、公司详情等功能。本指南详细说明如何使用API接口获取美股相关数据，所有接口均返回标准JSON格式。

二、接入准备

1. API认证

• 所有接口请求需在URL参数中包含有效的API密钥
• 可通过官方渠道申请测试或正式环境密钥
• 基础认证参数：key=your_api_key_here

2. 基础配置

• 接口地址：https://api.stocktv.top
• 支持协议：HTTPS
• 数据格式：JSON
• 字符编码：UTF-8

三、美股市场接口

1. 股票列表查询

获取美股市场股票列表，支持分页和交易所筛选。

接口地址：GET /stock/stocks

请求参数：

{
  "countryId": 5,       // 必填，美国国家ID为5
  "pageSize": 20,       // 选填，每页记录数，默认10
  "page": 1,           // 选填，页码，默认1
  "exchangeId": 1,     // 选填，交易所ID（1:NYSE, 2:NASDAQ）
  "key": "your_key"    // 必填，API密钥
}

示例请求：

curl -X GET "https://api.stocktv.top/stock/stocks?countryId=5&pageSize=20&page=1&key=your_api_key"

响应结构：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "id": 7310,
        "symbol": "AAPL",
        "name": "Apple Inc",
        "last": 195.42,
        "chg": 2.15,
        "chgPct": 1.11,
        "high": 196.88,
        "low": 192.75,
        "volume": 45678900,
        "avgVolume": 51234500,
        "exchangeId": 2,
        "countryId": 5,
        "countryNameTranslated": "United States",
        "flag": "US",
        "open": true,
        "lastClose": 193.27,
        "pairType": "Equities",
        "time": 1755008213,
        "url": "/equities/apple-inc"
      }
    ],
    "total": 5832,
    "size": 20,
    "current": 1,
    "pages": 292
  }
}

关键字段说明：

• id: 股票唯一标识（PID），用于其他接口查询
• symbol: 股票交易代码
• exchangeId: 交易所标识（1:NYSE, 2:NASDAQ）
• open: 交易状态（true:开市, false:休市）

2. 个股详情查询

根据多种条件查询单个股票详细信息。

接口地址：GET /stock/queryStocks

请求参数：

// 支持以下任一查询条件
id: 7310,           // 股票PID
symbol: "AAPL",     // 股票代码
name: "Apple Inc",  // 公司名称
url: "/equities/apple-inc"  // 详情页URL

示例请求：

# 通过PID查询
curl -X GET "https://api.stocktv.top/stock/queryStocks?id=7310&key=your_key"

# 通过股票代码查询
curl -X GET "https://api.stocktv.top/stock/queryStocks?symbol=AAPL&key=your_key"

响应包含技术指标：

{
  "technicalDay": "strong_buy",      // 日线技术信号
  "technicalHour": "buy",           // 小时线技术信号
  "technicalMonth": "neutral",      // 月线技术信号
  "technicalWeek": "buy",           // 周线技术信号
  "fundamentalBeta": 1.23,          // Beta系数
  "fundamentalMarketCap": 3050000000000,  // 市值
  "fundamentalRevenue": "383.29B"   // 营收
}

3. 批量股票查询

一次请求获取多个股票的实时数据。

接口地址：GET /stock/stocksByPids

请求参数：

pids: "7310,17976,24582"  // 必填，PID列表，逗号分隔

使用场景：

• 自选股列表实时更新
• 投资组合监控
• 多股票对比分析

4. 美股指数数据

获取美国主要股票指数信息。

接口地址：GET /stock/indices

请求参数：

countryId: 5,      // 美国国家ID
flag: "US",        // 选填，国家代码

美国主要指数：

• 道琼斯工业平均指数（DJI）
• 纳斯达克综合指数（IXIC）
• 标普500指数（SPX）
• 罗素2000指数（RUT）

响应示例：

{
  "id": 12345,
  "name": "S&P 500",
  "symbol": "SPX",
  "last": 5450.25,
  "chg": 35.50,
  "chgPct": 0.66,
  "isOpen": true,
  "time": 1755008213
}

5. 历史K线数据

获取股票的历史价格数据，支持多种时间周期。

接口地址：GET /stock/kline

时间周期参数：

示例请求：

# 获取苹果公司日K线
curl -X GET "https://api.stocktv.top/stock/kline?pid=7310&interval=P1D&key=your_key"

K线数据结构：

{
  "time": 1754928000000,    // 时间戳（毫秒）
  "open": 192.50,           // 开盘价
  "high": 196.25,           // 最高价
  "low": 191.80,            // 最低价
  "close": 195.42,          // 收盘价
  "volume": 51234500,       // 成交量
  "vo": 1001203456.50       // 成交额
}

6. 涨跌排行榜

获取美股市场的实时涨跌排名。

接口地址：GET /stock/updownList

排行榜类型：

7. 公司基本信息

获取上市公司的详细资料。

接口地址：GET /stock/companies

响应字段：

{
  "companyName": "Apple Inc Company Profile",
  "description": "Apple Inc. designs, manufactures, and markets smartphones, personal computers, tablets, wearables, and accessories worldwide...",
  "industry": "Consumer Electronics",
  "sector": "Technology",
  "employeeCount": 164000,
  "market": "United States",
  "countryId": 5
}

8. 实时数据推送

通过WebSocket获取股票的实时行情更新。

连接地址：

wss://ws-api.stocktv.top/connect?key=your_api_key

JavaScript示例：

const ws = new WebSocket('wss://ws-api.stocktv.top/connect?key=your_key');

ws.onopen = () => {
  console.log('WebSocket连接已建立');
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('实时数据:', data);
  
  // 数据处理示例
  if (data.type === 1) {  // 股票类型
    updateStockPrice(data.pid, {
      price: data.last_numeric,
      change: data.pc,
      changePercent: data.pcp,
      volume: data.turnover_numeric
    });
  }
};

// 心跳保持连接
setInterval(() => {
  if (ws.readyState === WebSocket.OPEN) {
    ws.send(JSON.stringify({ type: 'ping' }));
  }
}, 30000);

WebSocket数据格式：

{
  "pid": "7310",
  "last_numeric": "195.42",
  "bid": "195.40",
  "ask": "195.44",
  "high": "196.88",
  "low": "192.75",
  "last_close": "193.27",
  "pc": "+2.15",
  "pcp": "+1.11%",
  "turnover_numeric": "45678900",
  "time": "16:00:00",
  "timestamp": "1755008213",
  "type": 1
}

四、数据更新与延迟

1. 实时性说明

• 股票数据：1-3秒延迟
• 指数数据：5-10秒延迟
• 历史数据：T+1更新

2. 交易时间

• 美东时间：9:30-16:00
• 盘前交易：4:00-9:30
• 盘后交易：16:00-20:00
• open字段标识当前交易状态

五、错误处理

1. 通用响应格式

{
  "code": 200,            // 状态码
  "message": "操作成功",   // 状态信息
  "data": {}             // 业务数据
}

2. 常见状态码

3. 异常处理示例

async function fetchStockData(pid) {
  try {
    const response = await fetch(
      `https://api.stocktv.top/stock/kline?pid=${pid}&interval=P1D&key=${API_KEY}`
    );
    const result = await response.json();
    
    if (result.code === 200) {
      return result.data;
    } else {
      console.error(`API错误 ${result.code}: ${result.message}`);
      return null;
    }
  } catch (error) {
    console.error('网络请求失败:', error);
    return null;
  }
}

六、最佳实践

1. 性能优化

// 批量查询替代循环单查
const pids = ['7310', '24582', '38291'].join(',');
const url = `https://api.stocktv.top/stock/stocksByPids?pids=${pids}&key=${API_KEY}`;

// 合理设置缓存
const CACHE_DURATION = 30000; // 30秒
let lastFetchTime = 0;
let cachedData = null;

async function getCachedData() {
  const now = Date.now();
  if (!cachedData || (now - lastFetchTime) > CACHE_DURATION) {
    cachedData = await fetchData();
    lastFetchTime = now;
  }
  return cachedData;
}

2. 频率控制

• 公开接口：建议1-5秒/次
• WebSocket：实时推送无需轮询
• 历史数据：按需加载，避免频繁请求

3. 数据更新策略

// 实时数据使用WebSocket
const ws = new WebSocket(`wss://ws-api.stocktv.top/connect?key=${API_KEY}`);

// 非交易时间使用定时查询
if (marketIsOpen()) {
  // 使用WebSocket实时推送
} else {
  // 使用HTTP定时查询，间隔可适当延长
  setInterval(fetchStockData, 60000); // 1分钟
}

七、常见应用场景

1. 股票行情展示

<div class="stock-widget">
  <div class="stock-header">
    <span class="symbol">AAPL</span>
    <span class="name">Apple Inc</span>
  </div>
  <div class="stock-price">
    <span class="price">195.42</span>
    <span class="change positive">+2.15 (+1.11%)</span>
  </div>
  <div class="stock-details">
    <div>高: 196.88</div>
    <div>低: 192.75</div>
    <div>量: 45.68M</div>
  </div>
</div>

2. K线图表集成

// 使用ECharts绘制K线图
async function renderKLineChart(pid) {
  const klineData = await fetchKLineData(pid, 'P1D', 100);
  
  const chart = echarts.init(document.getElementById('chart'));
  const option = {
    xAxis: { data: klineData.map(item => formatTime(item.time)) },
    yAxis: { scale: true },
    series: [{
      type: 'candlestick',
      data: klineData.map(item => [
        item.open,
        item.close,
        item.low,
        item.high
      ])
    }]
  };
  
  chart.setOption(option);
}

3. 实时监控系统

class StockMonitor {
  constructor(stockList) {
    this.stocks = new Map();
    this.ws = null;
    this.initWebSocket();
  }
  
  initWebSocket() {
    this.ws = new WebSocket(`wss://ws-api.stocktv.top/connect?key=${API_KEY}`);
    
    this.ws.onmessage = (event) => {
      const data = JSON.parse(event.data);
      this.updateStock(data);
      
      // 触发价格预警
      this.checkAlerts(data);
    };
  }
  
  updateStock(data) {
    const stock = this.stocks.get(data.pid);
    if (stock) {
      Object.assign(stock, data);
      this.emit('update', stock);
    }
  }
  
  checkAlerts(data) {
    // 实现价格预警逻辑
  }
}

八、注意事项

1. API密钥安全：不要在前端代码中硬编码密钥，建议通过后端代理
2. 数据使用：遵守相关法律法规和交易所规定
3. 服务状态：关注API服务状态，建立容错机制
4. 版本兼容：注意API版本更新，及时调整接口调用
5. 文档参考：定期查阅官方文档获取最新接口信息

九、技术支持与资源

1. 官方资源

• API文档：持续更新，建议定期查阅
• 示例代码：GitHub提供多种语言示例
• 技术论坛：开发者交流社区

2. 问题排查

• 查看响应状态码和错误信息
• 验证请求参数格式
• 检查网络连接和代理设置
• 确认API密钥有效性

3. 社区支持

• Stack Overflow相关标签
• GitHub Issue提交
• 技术博客和教程

本指南提供了StockTV美股API的完整对接方案，涵盖从基础查询到高级应用的各个场景。开发者可根据实际需求选择合适的接口和技术方案，构建稳定、高效的股票数据应用。