一、接口概览
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 |