美国股票市场数据API的完整对接指南，包含NYSE、NASDAQ等主要交易所的实时行情、历史数据、公司信息等核心功能

一、接口概览

1.1 支持交易所

交易所代码	交易所名称	覆盖股票数量
NYSE	纽约证券交易所	2800+
NASDAQ	纳斯达克交易所	3300+
AMEX	美国证券交易所	500+

1.2 数据特性

• 实时行情：毫秒级延迟
• 历史数据：支持最长20年历史K线
• 基本面数据：包含PE比率、市值等指标
• 多维度数据：指数、盘前盘后、期权数据
• 数据格式：统一JSON格式
• 货币单位：所有价格均为美元(USD)

二、接入准备

2.1 获取API Key

联系官方获取密钥：https://stocktv.top

2.2 请求基础URL

https://api.stocktv.top

2.3 请求头设置

X-Api-Key: YOUR_API_KEY
Content-Type: application/json

三、核心接口说明

3.1 市场列表接口

获取美国交易所股票列表

接口地址：

GET /stock/stocks

请求参数：

参数	必选	说明	示例值
countryId	是	国家ID(美国为1)	1
exchangeId	否	交易所ID(1=NYSE, 2=NASDAQ)	1
pageSize	否	每页数量	100
page	否	页码	1

响应示例：

{"code": 200,"data": {"records": [{"id": 7203,           // 股票唯一ID"symbol": "AAPL",     // 股票代码"name": "Apple Inc.","last": 175.43,       // 最新价"chgPct": 1.25,       // 涨跌幅%"volume": 58439210,   // 成交量"high": 175.85,       // 当日最高"low": 173.90,        // 当日最低"open": true,         // 是否开市"cfd": false,         // 是否为CFD"marketCap": 2735000000000 // 市值(美元)}],"total": 3300,"pages": 33}
}

3.2 股票详情查询

获取指定股票实时行情

接口地址：

GET /stock/queryStocks

请求参数：

参数	必选	说明	示例值
id	是	股票ID	7203

响应示例：

{"code": 200,"data": [{"id": 7203,"symbol": "AAPL","name": "Apple Inc.","last": 175.43,"prevClose": 173.75,     // 前收盘价"open": 174.20,          // 开盘价"high": 175.85,"low": 173.90,"volume": 58439210,"avgVolume": 45218900,   // 平均成交量"peRatio": 28.7,         // 市盈率"eps": 6.11,             // 每股收益"dividendYield": 0.55,   // 股息率"beta": 1.23,            // Beta值"sector": "Technology"   // 行业分类}]
}

3.3 指数数据

获取美国主要指数行情

接口地址：

GET /stock/indices

请求参数：

参数	必选	说明	示例值
countryId	是	国家ID(美国为1)	1

响应示例：

{"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,"prevClose": 38424.75,"time": 1716458537      // 更新时间戳},{"id": 2,"symbol": "SPX",        // 标普500指数"name": "S&P 500 Index","last": 5125.60,"change": 18.25,"changePct": 0.36,"high": 5130.45,"low": 5110.20,"prevClose": 5107.35,"time": 1716458537},{"id": 3,"symbol": "IXIC",       // 纳斯达克指数"name": "NASDAQ Composite","last": 16250.80,"change": 75.30,"changePct": 0.47,"high": 16280.50,"low": 16180.25,"prevClose": 16175.50,"time": 1716458537}]
}

3.4 历史K线数据

获取股票历史价格数据

接口地址：

GET /stock/kline

请求参数：

参数	必选	说明	示例值
pid	是	股票ID	7203
interval	是	时间粒度	PT15M(15分钟) P1D(日线)

响应示例：

{"code": 200,"data": [{"time": 1725004800000, // 时间戳(ms)"open": 174.20,"high": 175.85,"low": 173.90,"close": 175.43,"volume": 58439210},{"time": 1725003900000,"open": 173.75,"high": 174.50,"low": 173.50,"close": 174.20,"volume": 45218900}]
}

四、高级数据接口

4.1 盘前盘后数据

获取盘前盘后交易数据

接口地址：

GET /us/prepost

请求参数：

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

响应示例：

{"code": 200,"data": {"preMarket": {"lastPrice": 176.20,"change": 0.77,"changePercent": 0.44,"volume": 1254321,"time": "07:45:23"},"postMarket": {"lastPrice": 175.80,"change": 0.37,"changePercent": 0.21,"volume": 876543,"time": "18:32:11"}}
}

4.2 期权数据

获取期权合约信息

接口地址：

GET /us/options

请求参数：

参数	必选	说明	示例值
symbol	是	股票代码	AAPL
expiration	否	到期日期(YYYYMMDD)	20241220

响应示例：

{"code": 200,"data": {"symbol": "AAPL","expirations": ["2024-12-20", "2025-01-17", "2025-03-21"],"options": [{"contractId": "AAPL241220C00175000","strike": 175.00,       // 行权价"lastPrice": 6.45,      // 最后成交价"bid": 6.40,            // 买价"ask": 6.50,            // 卖价"volume": 1245,         // 成交量"openInterest": 5423,   // 未平仓合约"impliedVolatility": 0.35, // 隐含波动率"type": "call"          // 看涨/看跌}]}
}

4.3 财务数据

获取公司财务报表

接口地址：

GET /us/financials

请求参数：

极速	必选	说明	示例值
symbol	是	股票代码	AAPL
period	否	年度/季度	annual, quarterly

响应示例：

{"code": 200,"data": {"symbol": "AAPL","financials": {"2023": {"revenue": 383285000000,   // 营收"grossProfit": 169148000000, // 毛利润"netIncome": 96950000000,   // 净利润"eps": 6.11,               // 每股收益"dividend": 0.96            // 每股股息},"2022": {"revenue": 365817000000,"grossProfit": 152836000000,"netIncome": 99803000000,"eps": 6.05,"dividend": 0.92}}}
}

五、实时数据推送

5.1 WebSocket连接

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

5.2 订阅消息

{"action": "subscribe","pids": [7203, 7204]  // 订阅的股票ID列表
}

5.3 实时数据格式

{"pid": "7203",         // 股票ID"symbol": "AAPL",      // 股票代码"last": "175.43",      // 最新价"change": "1.68",      // 涨跌额"changePct": "0.97",   // 涨跌幅%"volume": "58439210",  // 成交量"bid": "175.42",       // 买一价"ask": "175.44",       // 卖一价"high": "175.85",      // 当日最高"low": "173.90",       // 当日最低"open": "174.20",      // 开盘价"prevClose": "173.75", // 前收盘"timestamp": 1725008213 // 更新时间
}

5.4 心跳机制

客户端需每30秒发送心跳消息：

{"action": "ping"}

六、代码示例

6.1 Python获取股票数据

import requestsdef get_us_stocks():"""获取美国股票列表"""url = "https://api.stocktv.top/stock/stocks"params = {"countryId": 1,     # 美国国家ID"exchangeId": 2,    # NASDAQ交易所"pageSize": 100,"key": "YOUR_API_KEY"}try:response = requests.get(url, params=params)if response.status_code == 200:data = response.json()if data["code"] == 200:for stock in data["data"]["records"]:print(f"{stock['symbol']}: {stock['name']} - ${stock['last']}")else:print(f"API Error: {data['message']}")else:print(f"Request failed with status: {response.status_code}")except Exception as e:print(f"Error fetching stock list: {str(e)}")# 调用函数
get_us_stocks()

6.2 Java实时数据订阅

import org.java_websocket.client.WebSocketClient;
import org.java_websocket.handshake.ServerHandshake;import java.net.URI;public class USStockWS extends WebSocketClient {public USStockWS(URI serverUri) {super(serverUri);}@Overridepublic void onOpen(ServerHandshake handshakedata) {System.out.println("Connected to US Stock API");// 订阅AAPL和MSFT股票send("{\"action\":\"subscribe\",\"pids\":[7203, 7204]}");}@Overridepublic void onMessage(String message) {System.out.println("Received: " + message);// 实际应用中解析JSON并处理实时数据}@Overridepublic void onClose(int code, String reason, boolean remote) {System.out.println("Connection closed: " + reason);}@Overridepublic void onError(Exception ex) {ex.printStackTrace();}public static void main(String[] args) {String wsUrl = "wss://ws-api.stocktv.top/connect?key=YOUR_API_KEY";USStockWS client = new USStockWS(URI.create(wsUrl));client.connect();}
}

6.3 Node.js获取K线数据

const axios = require('axios');async function getKlineData() {try {const response = await axios.get('https://api.stocktv.top/stock/kline', {params: {pid: 7203,        // AAPL股票IDinterval: 'P1D'   // 日线数据},headers: {'X-Api-Key': 'YOUR_API_KEY'}});console.log('AAPL Historical Data:');response.data.data.forEach(kline => {const date = new Date(kline.time);console.log(`${date.toISOString().split('T')[0]}: $${kline.open} - $${kline.close}`);});} catch (error) {console.error('API Error:', error.response ? error.response.data : error.message);}
}getKlineData();

七、最佳实践

7.1 数据缓存策略

from cachetools import TTLCache
import time# 创建缓存，有效期5秒
stock_cache = TTLCache(maxsize=100, ttl=5)def get_stock_quote(stock_id):"""获取股票行情（带缓存）"""# 检查缓存if stock_id in stock_cache:return stock_cache[stock_id]# 调用API获取数据quote = fetch_from_api(stock_id)# 存入缓存if quote:stock_cache[stock_id] = quotereturn quote

7.2 错误处理与重试

import requests
import timedef fetch_with_retry(url, params, max_retries=3):"""带重试机制的API请求"""for attempt in range(max_retries):try:response = requests.get(url, params=params, timeout=5)if response.status_code == 200:data = response.json()if data.get("code") == 200:return dataelif data.get("code") == 429:  # 请求过多retry_after = int(data.get("retryAfter", 10))print(f"请求过于频繁，等待 {retry_after} 秒后重试...")time.sleep(retry_after)else:print(f"API返回错误: {data.get('message')}")else:print(f"请求失败，状态码: {response.status_code}")except Exception as e:print(f"请求异常: {str(e)}")if attempt < max_retries - 1:wait = 2 ** attempt  # 指数退避print(f"等待 {wait} 秒后重试 (尝试 {attempt+1}/{max_retries})")time.sleep(wait)print(f"请求失败，已达最大重试次数 {max_retries}")return None

7.3 实时数据批处理

class RealTimeBatchProcessor:def __init__(self, batch_size=10, batch_interval=0.5):self.batch_size = batch_sizeself.batch_interval = batch_intervalself.buffer = {}self.last_process_time = time.time()def add_data(self, symbol, data):"""添加实时数据到缓冲区"""if symbol not in self.buffer:self.buffer[symbol] = []self.buffer[symbol].append(data)# 检查是否达到批处理条件current_time = time.time()if (len(self.buffer[symbol]) >= self极速_size or current_time - self.last_process_time >= self.batch_interval):self.process_batch(symbol)self.last_process_time = current_timedef process_batch(self, symbol):"""处理缓冲区的数据"""if symbol not in self.buffer or not self.buffer[symbol]:returndata_points = self.buffer[symbol]# 计算统计指标prices = [d["last"] for d in data_points]volumes = [d["volume"] for d in data_points]avg_price = sum(prices) / len(prices)max_price = max(prices)min_price = min(prices)total_volume = sum(volumes)print(f"\n{symbol} 实时数据统计 (最近 {len(data_points)} 个更新):")print(f"平均价格: ${avg_price:.2f}, 最高: ${max_price:.2f}, 最低: ${min_price:.2f}")print(f"总成交量: {total_volume}")# 清空缓冲区self.buffer[symbol] = []

八、数据字典

8.1 美国主要指数

代码	指数名称	说明
DJI	道琼斯工业平均指数	30家大型蓝筹股
SPX	标普500指数	500家大型公司
IXIC	纳斯达克综合指数	所有纳斯达克上市公司
RUT	罗素2000指数	2000家小型公司

8.2 交易时间（美国东部时间）

交易时段	时间	说明
盘前交易	04:00-09:30	盘前交易时段
常规交易	09:30-16:00	主要交易时段
盘后交易	16:00-20:00	盘后交易时段

8.3 行业分类

分类代码	行业名称
TECHNOLOGY	科技
FINANCIAL	金融
HEALTHCARE	医疗保健
CONSUMER	消费品
INDUSTRIAL	工业

10.2 错误代码表

错误码	含义	解决方案
400	Request parameter error	Check request parameters
401	Authentication error	Check API Key
403	Access denied	Check account privileges
404	Data not found	Check symbol
429	Too many requests	Reduce request frequency
500	Server error	Contact technical support