一、概述
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
时间周期参数：
| interval | 说明 | 适用场景 |
|---|
| PT5M | 5分钟线 | 日内交易 |
| PT15M | 15分钟线 | 短线分析 |
| PT1H | 1小时线 | 趋势分析 |
| P1D | 日线 | 技术分析 |
| P1W | 周线 | 长期趋势 |
| P1M | 月线 | 投资决策 |
示例请求：
# 获取苹果公司日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
排行榜类型：
| type | 说明 | 数据量 |
|---|
| 1 | 涨幅榜 | 前50名 |
| 2 | 跌幅榜 | 前50名 |
| 3 | 涨停榜 | 实时数据 |
| 4 | 跌停榜 | 实时数据 |
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. 常见状态码
| 状态码 | 说明 | 处理建议 |
|---|
| 200 | 请求成功 | 正常处理数据 |
| 400 | 参数错误 | 检查请求参数 |
| 401 | 认证失败 | 验证API密钥 |
| 404 | 接口不存在 | 检查接口地址 |
| 429 | 请求频繁 | 降低调用频率 |
| 500 | 服务器错误 | 稍后重试 |
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) {
// 实现价格预警逻辑
}
}
八、注意事项
- API密钥安全：不要在前端代码中硬编码密钥，建议通过后端代理
- 数据使用：遵守相关法律法规和交易所规定
- 服务状态：关注API服务状态，建立容错机制
- 版本兼容：注意API版本更新，及时调整接口调用
- 文档参考：定期查阅官方文档获取最新接口信息
九、技术支持与资源
1. 官方资源
- API文档：持续更新，建议定期查阅
- 示例代码：GitHub提供多种语言示例
- 技术论坛：开发者交流社区
2. 问题排查
- 查看响应状态码和错误信息
- 验证请求参数格式
- 检查网络连接和代理设置
- 确认API密钥有效性
3. 社区支持
- Stack Overflow相关标签
- GitHub Issue提交
- 技术博客和教程
本指南提供了StockTV美股API的完整对接方案，涵盖从基础查询到高级应用的各个场景。开发者可根据实际需求选择合适的接口和技术方案，构建稳定、高效的股票数据应用。
