美股市场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-XGET"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,// 股票PIDsymbol:"AAPL",// 股票代码name:"Apple Inc",// 公司名称url:"/equities/apple-inc"// 详情页URL

示例请求：

# 通过PID查询curl-XGET"https://api.stocktv.top/stock/queryStocks?id=7310&key=your_key"# 通过股票代码查询curl-XGET"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,// 美国国家IDflag:"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-XGET"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示例：

constws=newWebSocket('wss://ws-api.stocktv.top/connect?key=your_key');ws.onopen=()=>{console.log('WebSocket连接已建立');};ws.onmessage=(event)=>{constdata=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. 异常处理示例

asyncfunctionfetchStockData(pid){try{constresponse=awaitfetch(`https://api.stocktv.top/stock/kline?pid=${pid}&interval=P1D&key=${API_KEY}`);constresult=awaitresponse.json();if(result.code===200){returnresult.data;}else{console.error(`API错误${result.code}:${result.message}`);returnnull;}}catch(error){console.error('网络请求失败:',error);returnnull;}}

六、最佳实践

1. 性能优化

// 批量查询替代循环单查constpids=['7310','24582','38291'].join(',');consturl=`https://api.stocktv.top/stock/stocksByPids?pids=${pids}&key=${API_KEY}`;// 合理设置缓存constCACHE_DURATION=30000;// 30秒letlastFetchTime=0;letcachedData=null;asyncfunctiongetCachedData(){constnow=Date.now();if(!cachedData||(now-lastFetchTime)>CACHE_DURATION){cachedData=awaitfetchData();lastFetchTime=now;}returncachedData;}

2. 频率控制

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

3. 数据更新策略

// 实时数据使用WebSocketconstws=newWebSocket(`wss://ws-api.stocktv.top/connect?key=${API_KEY}`);// 非交易时间使用定时查询if(marketIsOpen()){// 使用WebSocket实时推送}else{// 使用HTTP定时查询，间隔可适当延长setInterval(fetchStockData,60000);// 1分钟}

七、常见应用场景

1. 股票行情展示

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

2. K线图表集成

// 使用ECharts绘制K线图asyncfunctionrenderKLineChart(pid){constklineData=awaitfetchKLineData(pid,'P1D',100);constchart=echarts.init(document.getElementById('chart'));constoption={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. 实时监控系统

classStockMonitor{constructor(stockList){this.stocks=newMap();this.ws=null;this.initWebSocket();}initWebSocket(){this.ws=newWebSocket(`wss://ws-api.stocktv.top/connect?key=${API_KEY}`);this.ws.onmessage=(event)=>{constdata=JSON.parse(event.data);this.updateStock(data);// 触发价格预警this.checkAlerts(data);};}updateStock(data){conststock=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的完整对接方案，涵盖从基础查询到高级应用的各个场景。开发者可根据实际需求选择合适的接口和技术方案，构建稳定、高效的股票数据应用。