美股市场股票数据API对接文档

本文档提供StockTV美股市场数据API的完整对接指南，涵盖实时行情、历史数据、公司信息、财务指标等核心功能

一、接口概览

1.1 支持交易所

交易所代码交易所名称主要上市公司NYSE纽约证券交易所蓝筹股、传统行业巨头NASDAQ纳斯达克交易所科技股、成长型公司AMEX美国证券交易所中小型公司、ETF1.2 数据特性

• 实时行情：毫秒级延迟（WebSocket）
  
• 历史数据：支持最长20年历史数据
  
• 基本面数据：完整财务指标、分析师评级
  
• 多维度数据：分时K线、盘前盘后、期权数据
  
• 数据格式：统一JSON格式
  

二、接入准备

2.1 获取API Key

联系官方获取密钥：https://t.me/CryptoRzz
2.2 请求基础URL

1. https://api.stocktv.top

复制代码

2.3 请求头设置

1. X-Api-Key: YOUR_API_KEY
2. Content-Type: application/json

复制代码

三、核心接口说明

3.1 股票实时行情

获取单只股票实时数据
接口地址：

1. GET /us/quote

复制代码

请求参数：
参数必选说明示例值symbol是股票代码AAPL响应示例：

1. {
2.   "code": 200,
3.   "data": {
4.     "symbol": "AAPL",
5.     "name": "Apple Inc.",
6.     "exchange": "NASDAQ",
7.     "price": 175.43,           // 最新价
8.     "prevClose": 173.75,       // 前收盘
9.     "open": 174.20,            // 开盘价
10.     "high": 175.85,            // 最高价
11.     "low": 173.90,             // 最低价
12.     "volume": 58439210,        // 成交量
13.     "marketCap": 2735000000000,// 市值(美元)
14.     "peRatio": 28.7,           // 市盈率
15.     "eps": 6.11,               // 每股收益
16.     "dividendYield": 0.55,     // 股息率
17.     "beta": 1.23,              // Beta值
18.     "lastUpdated": 1725008213  // 最后更新时间戳
19.   }
20. }

复制代码

3.2 批量查询行情

获取多只股票实时数据
接口地址：

1. POST /us/batch-quotes

复制代码

请求体：

1. {
2.   "symbols": ["AAPL", "MSFT", "GOOGL"]
3. }

复制代码

响应示例：

1. {
2.   "code": 200,
3.   "data": {
4.     "AAPL": {
5.       "price": 175.43,
6.       "change": 1.68,
7.       "changePercent": 0.97
8.     },
9.     "MSFT": {
10.       "price": 342.54,
11.       "change": -0.86,
12.       "changePercent": -0.25
13.     },
14.     "GOOGL": {
15.       "price": 143.28,
16.       "change": 2.15,
17.       "changePercent": 1.52
18.     }
19.   }
20. }

复制代码

3.3 历史K线数据

获取股票历史价格
接口地址：

1. GET /us/historical

复制代码

请求参数：
参数必选说明示例值symbol是股票代码AAPLperiod否时间周期1d, 1w, 1m, 3m, 6m, 1y, 5yinterval否时间粒度1m, 5m, 15m, 30m, 1h, 1dstart否开始日期(YYYYMMDD)20230901end否结束日期(YYYYMMDD)20230930响应示例：

1. {
2.   "code": 200,
3.   "data": [
4.     {
5.       "date": "2023-09-01",
6.       "open": 174.20,
7.       "high": 175.85,
8.       "low": 173.90,
9.       "close": 175.43,
10.       "volume": 58439210,
11.       "adjClose": 175.43
12.     },
13.     {
14.       "date": "2023-08-31",
15.       "open": 173.15,
16.       "high": 174.25,
17.       "low": 172.80,
18.       "close": 173.75,
19.       "volume": 52387125,
20.       "adjClose": 173.75
21.     }
22.   ]
23. }

复制代码

3.4 公司基本信息

获取公司概况
接口地址：

1. GET /us/company

复制代码

请求参数：
参数必选说明示例值symbol是股票代码AAPL响应示例：

1. {
2.   "code": 200,
3.   "data": {
4.     "symbol": "AAPL",
5.     "name": "Apple Inc.",
6.     "description": "全球领先的科技公司，设计、制造和销售智能手机、个人电脑、平板电脑、可穿戴设备和配件...",
7.     "sector": "Technology",
8.     "industry": "Consumer Electronics",
9.     "ceo": "Tim Cook",
10.     "employees": 164000,
11.     "headquarters": "Cupertino, California",
12.     "website": "https://www.apple.com",
13.     "ipoDate": "1980-12-12"
14.   }
15. }

复制代码

3.5 财务数据

获取财务指标
接口地址：

1. GET /us/financials

复制代码

请求参数：
参数必选说明示例值symbol是股票代码AAPLperiod否年度/季度annual, quarterly响应示例：

1. {
2.   "code": 200,
3.   "data": {
4.     "symbol": "AAPL",
5.     "financials": {
6.       "2023": {
7.         "revenue": 383285000000,   // 营收
8.         "grossProfit": 169148000000, // 毛利润
9.         "netIncome": 96950000000,   // 净利润
10.         "eps": 6.11,               // 每股收益
11.         "dividend": 0.96            // 每股股息
12.       },
13.       "2022": {
14.         "revenue": 365817000000,
15.         "grossProfit": 152836000000,
16.         "netIncome": 99803000000,
17.         "eps": 6.05,
18.         "dividend": 0.92
19.       }
20.     }
21.   }
22. }

复制代码

四、高级数据接口

4.1 分时数据

获取当日分时数据
接口地址：

1. GET /us/intraday

复制代码

请求参数：
参数必选说明示例值symbol是股票代码AAPLinterval否时间粒度(1m, 5m)5m响应示例：

1. {
2.   "code": 200,
3.   "data": [
4.     {
5.       "timestamp": 1725004800000, // 时间戳(毫秒)
6.       "price": 174.32,
7.       "volume": 125432
8.     },
9.     {
10.       "timestamp": 1725005100000,
11.       "price": 174.56,
12.       "volume": 143256
13.     }
14.   ]
15. }

复制代码

4.2 盘前盘后数据

获取盘前盘后交易数据
接口地址：

1. GET /us/prepost

复制代码

请求参数：
参数必选说明示例值symbol是股票代码AAPL响应示例：

1. {
2.   "code": 200,
3.   "data": {
4.     "preMarket": {
5.       "lastPrice": 176.20,
6.       "change": 0.77,
7.       "changePercent": 0.44,
8.       "volume": 1254321,
9.       "time": "07:45:23"
10.     },
11.     "postMarket": {
12.       "lastPrice": 175.80,
13.       "change": 0.37,
14.       "changePercent": 0.21,
15.       "volume": 876543,
16.       "time": "18:32:11"
17.     }
18.   }
19. }

复制代码

4.3 期权数据

获取期权合约信息
接口地址：

1. GET /us/options

复制代码

请求参数：
参数必选说明示例值symbol是股票代码AAPLexpiration否到期日期(YYYYMMDD)20231215响应示例：

1. {
2.   "code": 200,
3.   "data": {
4.     "symbol": "AAPL",
5.     "expirations": ["2023-12-15", "2024-01-19", "2024-03-15"],
6.     "options": [
7.       {
8.         "contractId": "AAPL231215C00175000",
9.         "strike": 175.00,       // 行权价
10.         "lastPrice": 6.45,      // 最后成交价
11.         "bid": 6.40,            // 买价
12.         "ask": 6.50,            // 卖价
13.         "volume": 1245,         // 成交量
14.         "openInterest": 5423,   // 未平仓合约
15.         "impliedVolatility": 0.35, // 隐含波动率
16.         "type": "call"          // 看涨/看跌
17.       }
18.     ]
19.   }
20. }

复制代码

五、实时数据推送

5.1 WebSocket连接

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

复制代码

5.2 订阅消息

1. {
2.   "action": "subscribe",
3.   "symbols": ["AAPL", "MSFT", "TSLA"]
4. }

复制代码

5.3 实时数据格式

1. {
2.   "symbol": "AAPL",       // 股票代码
3.   "price": 175.43,        // 最新价
4.   "change": 1.68,         // 涨跌额
5.   "changePercent": 0.97,  // 涨跌幅%
6.   "volume": 58439210,     // 成交量
7.   "bid": 175.42,          // 买一价
8.   "ask": 175.44,          // 卖一价
9.   "bidSize": 125,         // 买一量
10.   "askSize": 85,          // 卖一量
11.   "timestamp": 1725008213 // 时间戳
12. }

复制代码

5.4 心跳机制

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

1. {"action": "ping"}

复制代码

六、代码示例

6.1 Python获取股票数据

1. import requests
3. def get_stock_quote(symbol):
4.     url = "https://api.stocktv.top/us/quote"
5.     params = {"symbol": symbol}
6.     headers = {
7.         "X-Api-Key": "YOUR_API_KEY",
8.         "Content-Type": "application/json"
9.     }
10.    
11.     response = requests.get(url, params=params, headers=headers)
12.     if response.status_code == 200:
13.         data = response.json()
14.         if data["code"] == 200:
15.             return data["data"]
16.     return None
18. # 获取苹果股票数据
19. aapl = get_stock_quote("AAPL")
20. if aapl:
21.     print(f"{aapl['name']} ({aapl['symbol']})")
22.     print(f"价格: ${aapl['price']} ({aapl['changePercent']}%)")
23.     print(f"市值: ${aapl['marketCap']/1e9:.2f}B")

复制代码

6.2 Node.js实时数据订阅

1. const WebSocket = require('ws');
2. const ws = new WebSocket('wss://ws-api.stocktv.top/us?key=YOUR_API_KEY');
4. ws.on('open', () => {
5.   console.log('Connected to US Stock API');
6.   
7.   // 订阅股票
8.   ws.send(JSON.stringify({
9.     action: "subscribe",
10.     symbols: ["AAPL", "MSFT", "TSLA"]
11.   }));
12. });
14. ws.on('message', (data) => {
15.   const message = JSON.parse(data);
16.   if(message.symbol) {
17.     const arrow = message.change >= 0 ? '↑' : '↓';
18.     console.log(`[${message.symbol}] ${message.price} ${arrow} ${message.changePercent}%`);
19.   }
20. });
22. // 心跳维持
23. setInterval(() => {
24.   ws.send(JSON.stringify({action: "ping"}));
25. }, 30000);

复制代码

6.3 Java获取历史数据

1. import com.fasterxml.jackson.databind.ObjectMapper;
2. import okhttp3.OkHttpClient;
3. import okhttp3.Request;
4. import okhttp3.Response;
6. public class StockHistoryFetcher {
7.     private static final String API_KEY = "YOUR_API_KEY";
8.     private static final ObjectMapper mapper = new ObjectMapper();
10.     public static void main(String[] args) throws Exception {
11.         String symbol = "AAPL";
12.         String url = "https://api.stocktv.top/us/historical?symbol=" + symbol + "&period=1y";
13.         
14.         OkHttpClient client = new OkHttpClient();
15.         Request request = new Request.Builder()
16.                 .url(url)
17.                 .addHeader("X-Api-Key", API_KEY)
18.                 .build();
19.         
20.         try (Response response = client.newCall(request).execute()) {
21.             if (response.isSuccessful()) {
22.                 String json = response.body().string();
23.                 JsonNode root = mapper.readTree(json);
24.                 if (root.path("code").asInt() == 200) {
25.                     JsonNode data = root.path("data");
26.                     System.out.println("AAPL Historical Data:");
27.                     data.forEach(day -> {
28.                         System.out.printf("%s: Open=%.2f, Close=%.2f, Volume=%d%n",
29.                                 day.path("date").asText(),
30.                                 day.path("open").asDouble(),
31.                                 day.path("close").asDouble(),
32.                                 day.path("volume").asLong());
33.                     });
34.                 }
35.             }
36.         }
37.     }
38. }

复制代码

七、最佳实践

7.1 数据缓存策略

1. from cachetools import TTLCache
2. import time
4. class StockDataCache:
5.     def __init__(self, maxsize=100, ttl=60):
6.         self.cache = TTLCache(maxsize=maxsize, ttl=ttl)
7.    
8.     def get_quote(self, symbol):
9.         if symbol in self.cache:
10.             return self.cache[symbol]
11.         
12.         # 从API获取
13.         quote = api_get_quote(symbol)  # 实际API调用函数
14.         if quote:
15.             self.cache[symbol] = quote
16.         return quote
18. # 使用示例
19. cache = StockDataCache()
20. aapl = cache.get_quote("AAPL")

复制代码

7.2 批量请求优化

1. async function fetchBatchQuotes(symbols, batchSize=10) {
2.   const results = {};
3.   
4.   for (let i = 0; i < symbols.length; i += batchSize) {
5.     const batch = symbols.slice(i, i + batchSize);
6.     const response = await fetch('https://api.stocktv.top/us/batch-quotes', {
7.       method: 'POST',
8.       headers: {
9.         'X-Api-Key': API_KEY,
10.         'Content-Type': 'application/json'
11.       },
12.       body: JSON.stringify({ symbols: batch })
13.     });
14.    
15.     const data = await response.json();
16.     if (data.code === 200) {
17.       Object.assign(results, data.data);
18.     }
19.    
20.     // 避免请求过快
21.     await new Promise(resolve => setTimeout(resolve, 300));
22.   }
23.   
24.   return results;
25. }

复制代码

7.3 实时数据批处理

1. class RealTimeProcessor:
2.     def __init__(self, batch_size=10, batch_interval=0.5):
3.         self.buffer = {}
4.         self.batch_size = batch_size
5.         self.batch_interval = batch_interval
6.         self.last_process_time = time.time()
7.    
8.     def add_update(self, symbol, data):
9.         if symbol not in self.buffer:
10.             self.buffer[symbol] = []
11.         
12.         self.buffer[symbol].append(data)
13.         
14.         # 检查是否处理批次
15.         current_time = time.time()
16.         if (len(self.buffer[symbol]) >= self.batch_size or
17.             current_time - self.last_process_time >= self.batch_interval):
18.             self.process_batch(symbol)
19.             self.last_process_time = current_time
20.    
21.     def process_batch(self, symbol):
22.         data_points = self.buffer.get(symbol, [])
23.         if not data_points:
24.             return
25.         
26.         # 计算平均价格、总成交量等
27.         prices = [d['price'] for d in data_points]
28.         avg_price = sum(prices) / len(prices)
29.         total_volume = sum(d['volume'] for d in data_points)
30.         
31.         print(f"{symbol} 批次统计: {len(data_points)}次更新")
32.         print(f"平均价格: {avg_price:.2f}, 总成交量: {total_volume}")
33.         
34.         # 清空缓冲区
35.         self.buffer[symbol] = []

复制代码

7.4 错误处理与重试

1. public JsonNode fetchWithRetry(String url, int maxRetries) {
2.     int retries = 0;
3.     while (retries < maxRetries) {
4.         try {
5.             Request request = new Request.Builder()
6.                     .url(url)
7.                     .addHeader("X-Api-Key", API_KEY)
8.                     .build();
9.             
10.             try (Response response = client.newCall(request).execute()) {
11.                 if (response.isSuccessful()) {
12.                     return mapper.readTree(response.body().string());
13.                 } else if (response.code() == 429) {
14.                     // 请求过多，等待后重试
15.                     int waitTime = 30; // 默认等待30秒
16.                     String retryAfter = response.header("Retry-After");
17.                     if (retryAfter != null) {
18.                         waitTime = Integer.parseInt(retryAfter);
19.                     }
20.                     Thread.sleep(waitTime * 1000);
21.                 }
22.             }
23.         } catch (Exception e) {
24.             // 记录错误
25.         }
26.         retries++;
27.     }
28.     return null; // 达到最大重试次数
29. }

复制代码

八、数据字典

8.1 美股主要指数

代码指数名称包含公司.DJI道琼斯工业平均指数30家大型企业.IXIC纳斯达克综合指数所有纳斯达克上市公司.INX标普500指数500家大型公司.RUT罗素2000指数2000家小型公司8.2 交易时间

交易时段美东时间北京时间盘前交易04:00-09:3016:00-21:30常规交易09:30-16:0021:30-04:00(+1)盘后交易16:00-20:0004:00-08:00(+1)十、附录

10.1 常见问题解答

Q: 如何获取历史分时数据？
A: 使用/us/intraday接口，设置interval参数为1m
Q: 是否支持分页？
A: 对于列表接口（如历史数据），使用page和size参数控制数据范围
10.2 错误代码表

错误码含义解决方案400请求参数错误检查请求参数401未授权检查API Key404资源不存在检查请求路径429请求过于频繁降低请求频率500服务器错误联系技术支持

本文档版本：v3.0.1
最后更新：2025年9月5日
下载PDF版本：https://stocktv.top/
示例代码库：https://github.com/cryptorzz/

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！