获取美国股票数据API对接完全指南

获取美国股票数据API对接完全指南

本文提供美国股票市场（NYSE、NASDAQ）的完整API对接方案，包含实时行情、历史数据、公司信息等接口详解

API接口详情

1. 获取美国市场股票列表

​​接口地址​ ​: GET /stock/stocks ​​请求参数​​:

GET https://api.stocktv.top/stock/stocks?countryId=1&pageSize=10&page=1&key=您的API密钥

​​参数说明​​:

• countryId: 国家ID，美国为1
• pageSize: 每页显示数量，默认10
• page: 页码，默认1
• key: API访问密钥

​​响应示例​​:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "id": 1,
        "name": "Apple Inc",
        "symbol": "AAPL",
        "last": 175.45,
        "chg": 2.15,
        "chgPct": 1.24,
        "high": 176.20,
        "low": 173.80,
        "volume": 45678900,
        "avgVolume": 52100000,
        "countryNameTranslated": "United States",
        "flag": "US",
        "open": true,
        "time": 1716448222,
        "last_close": 173.30,
        "marketCap": "2.7T",
        "sector": "Technology",
        "industry": "Consumer Electronics"
      },
      {
        "id": 2,
        "name": "Microsoft Corporation",
        "symbol": "MSFT",
        "last": 345.60,
        "chg": -1.20,
        "chgPct": -0.35,
        "high": 348.90,
        "low": 344.50,
        "volume": 23456700,
        "avgVolume": 27800000,
        "countryNameTranslated": "United States",
        "flag": "US",
        "open": true,
        "time": 1716448222,
        "last_close": 346.80,
        "marketCap": "2.6T",
        "sector": "Technology",
        "industry": "Software---Infrastructure"
      }
    ],
    "total": 5000,
    "size": 10,
    "current": 1,
    "pages": 500
  }
}

2. 查询特定美股信息

​​接口地址​ ​: GET /stock/queryStocks ​​请求参数​​:

GET https://api.stocktv.top/stock/queryStocks?symbol=AAPL&key=您的API密钥

​​参数说明​​:

• id: 股票PID（可通过市场列表接口获取）
• name: 股票名称（可选）
• symbol: 股票代码（可选）
• key: API访问密钥

3. 获取美国市场指数

​​接口地址​ ​: GET /stock/indices ​​请求参数​​:

GET https://api.stocktv.top/stock/indices?countryId=1&key=您的API密钥

​​响应示例​​:

{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "id": 1001,
      "name": "Dow Jones Industrial Average",
      "symbol": "DJI",
      "last": 38787.65,
      "chg": 369.85,
      "chgPct": 0.96,
      "high": 38993.60,
      "low": 38577.45,
      "isOpen": true,
      "flag": "US",
      "time": 1716458537,
      "components": 30
    },
    {
      "id": 1002,
      "name": "S&P 500 Index",
      "symbol": "SPX",
      "last": 5120.35,
      "chg": 45.25,
      "chgPct": 0.89,
      "high": 5135.80,
      "low": 5090.45,
      "isOpen": true,
      "flag": "US",
      "time": 1716458537,
      "components": 505
    },
    {
      "id": 1003,
      "name": "NASDAQ Composite",
      "symbol": "IXIC",
      "last": 16720.85,
      "chg": 125.45,
      "chgPct": 0.76,
      "high": 16780.60,
      "low": 16550.30,
      "isOpen": true,
      "flag": "US",
      "time": 1716458537,
      "components": 2500
    }
  ]
}

4. 获取K线数据

​​接口地址​ ​: GET /stock/kline ​​请求参数​​:

GET https://api.stocktv.top/stock/kline?pid=1&interval=PT1H&key=您的API密钥

​​时间间隔参数​​:

• PT1M: 1分钟
• PT5M: 5分钟
• PT15M: 15分钟
• PT1H: 1小时
• P1D: 1天
• P1W: 1周
• P1M: 1月

5. 获取公司基本信息

​​接口地址​ ​: GET /stock/companies ​​请求参数​​:

GET https://api.stocktv.top/stock/companies?countryId=1&pageSize=5&page=1&key=您的API密钥

使用示例

Python获取美股数据示例

import requests
import pandas as pd
from datetime import datetime

class USStockAPI:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = "https://api.stocktv.top"
        self.country_id = 1  # 美国国家ID
    
    def get_us_stocks(self, page=1, page_size=20):
        """获取美国股票列表"""
        url = f"{self.base_url}/stock/stocks"
        params = {
            "countryId": self.country_id,
            "page": page,
            "pageSize": page_size,
            "key": self.api_key
        }
        
        try:
            response = requests.get(url, params=params, timeout=10)
            if response.status_code == 200:
                data = response.json()
                if data["code"] == 200:
                    return data["data"]
            return None
        except Exception as e:
            print(f"获取美股列表失败: {e}")
            return None
    
    def get_stock_detail(self, symbol):
        """获取股票详细信息"""
        url = f"{self.base_url}/stock/queryStocks"
        params = {
            "symbol": symbol,
            "key": self.api_key
        }
        
        try:
            response = requests.get(url, params=params, timeout=10)
            if response.status_code == 200:
                data = response.json()
                if data["code"] == 200 and data["data"]:
                    return data["data"][0]
            return None
        except Exception as e:
            print(f"获取股票详情失败: {e}")
            return None
    
    def get_major_indices(self):
        """获取美国主要指数"""
        url = f"{self.base_url}/stock/indices"
        params = {
            "countryId": self.country_id,
            "key": self.api_key
        }
        
        try:
            response = requests.get(url, params=params, timeout=10)
            if response.status_code == 200:
                data = response.json()
                if data["code"] == 200:
                    return data["data"]
            return None
        except Exception as e:
            print(f"获取指数数据失败: {e}")
            return None
    
    def get_historical_data(self, symbol, period="1mo", interval="1d"):
        """获取历史数据"""
        # 首先获取股票ID
        stock_info = self.get_stock_detail(symbol)
        if not stock_info:
            return None
        
        url = f"{self.base_url}/stock/kline"
        params = {
            "pid": stock_info["id"],
            "interval": f"P{interval.upper()}",
            "key": self.api_key
        }
        
        try:
            response = requests.get(url, params=params, timeout=10)
            if response.status_code == 200:
                data = response.json()
                if data["code"] == 200:
                    return data["data"]
            return None
        except Exception as e:
            print(f"获取历史数据失败: {e}")
            return None

# 使用示例
if __name__ == "__main__":
    API_KEY = "您的API密钥"
    
    us_api = USStockAPI(API_KEY)
    
    # 获取美股列表
    stocks = us_api.get_us_stocks(1, 10)
    if stocks and "records" in stocks:
        print("=== 美国股票列表 ===")
        for stock in stocks["records"]:
            change_icon = "↑" if stock["chg"] >= 0 else "↓"
            print(f"{stock['symbol']} - {stock['name']}: ${stock['last']} {change_icon}{abs(stock['chgPct'])}%")
    
    # 获取主要指数
    indices = us_api.get_major_indices()
    if indices:
        print("\n=== 美国主要指数 ===")
        for index in indices:
            change_icon = "↑" if index["chg"] >= 0 else "↓"
            print(f"{index['name']}: {index['last']} {change_icon}{abs(index['chgPct'])}%")
    
    # 获取特定股票详情（例如苹果）
    apple_stock = us_api.get_stock_detail("AAPL")
    if apple_stock:
        print(f"\n=== Apple公司详情 ===")
        print(f"当前价格: ${apple_stock['last']}")
        print(f"涨跌幅: {apple_stock['chg']} ({apple_stock['chgPct']}%)")
        print(f"成交量: {apple_stock['volume']}")
        print(f"市值: {apple_stock['marketCap']}")
        print(f"行业: {apple_stock['sector']} - {apple_stock['industry']}")

JavaScript获取美股数据

// 使用Fetch API获取美股数据
const API_KEY = '您的API密钥';
const BASE_URL = 'https://api.stocktv.top';
const COUNTRY_ID = 1; // 美国国家ID

class USStockData {
    // 获取美股列表
    async getStocks(page = 1, pageSize = 20) {
        const url = `${BASE_URL}/stock/stocks?countryId=${COUNTRY_ID}&page=${page}&pageSize=${pageSize}&key=${API_KEY}`;
        
        try {
            const response = await fetch(url);
            const data = await response.json();
            
            if (data.code === 200) {
                return data.data;
            }
            return null;
        } catch (error) {
            console.error('获取美股列表失败:', error);
            return null;
        }
    }

    // 获取股票详情
    async getStockDetail(symbol) {
        const url = `${BASE_URL}/stock/queryStocks?symbol=${symbol}&key=${API_KEY}`;
        
        try {
            const response = await fetch(url);
            const data = await response.json();
            
            if (data.code === 200 && data.data && data.data.length > 0) {
                return data.data[0];
            }
            return null;
        } catch (error) {
            console.error('获取股票详情失败:', error);
            return null;
        }
    }

    // 获取美国主要指数
    async getMajorIndices() {
        const url = `${BASE_URL}/stock/indices?countryId=${COUNTRY_ID}&key=${API_KEY}`;
        
        try {
            const response = await fetch(url);
            const data = await response.json();
            
            if (data.code === 200) {
                return data.data;
            }
            return null;
        } catch (error) {
            console.error('获取指数数据失败:', error);
            return null;
        }
    }

    // 更新页面显示
    updateStockDisplay(stocks) {
        const container = document.getElementById('us-stocks');
        container.innerHTML = '';
        
        stocks.forEach(stock => {
            const changeClass = stock.chg >= 0 ? 'positive' : 'negative';
            const changeIcon = stock.chg >= 0 ? '↑' : '↓';
            
            const stockElement = document.createElement('div');
            stockElement.className = 'stock-item';
            stockElement.innerHTML = `
                <div class="stock-symbol">${stock.symbol}</div>
                <div class="stock-name">${stock.name}</div>
                <div class="stock-price">$${stock.last.toFixed(2)}</div>
                <div class="stock-change ${changeClass}">
                    ${changeIcon} $${Math.abs(stock.chg).toFixed(2)} (${Math.abs(stock.chgPct).toFixed(2)}%)
                </div>
                <div class="stock-volume">成交量: ${(stock.volume / 1000000).toFixed(2)}M</div>
                <div class="stock-market-cap">市值: ${stock.marketCap}</div>
            `;
            container.appendChild(stockElement);
        });
    }
}

// 使用示例
const stockData = new USStockData();

// 页面加载时获取数据
document.addEventListener('DOMContentLoaded', async () => {
    const stocks = await stockData.getStocks(1, 10);
    if (stocks && stocks.records) {
        stockData.updateStockDisplay(stocks.records);
    }
    
    const indices = await stockData.getMajorIndices();
    if (indices) {
        console.log('美国主要指数:', indices);
    }
    
    // 获取苹果股票详情
    const appleStock = await stockData.getStockDetail('AAPL');
    if (appleStock) {
        console.log('苹果股票详情:', appleStock);
    }
});

// 定时更新数据
setInterval(async () => {
    const stocks = await stockData.getStocks(1, 10);
    if (stocks && stocks.records) {
        stockData.updateStockDisplay(stocks.records);
    }
}, 30000); // 每30秒更新一次

美股市场特色

主要指数

• ​道琼斯工业平均指数 (DJI)​ - 30家大型工业公司组成的价格加权指数
• ​标普500指数 (SPX)​ - 500家大型公司组成的市值加权指数
• ​纳斯达克综合指数 (IXIC)​ - 纳斯达克所有上市公司组成的指数
• ​罗素2000指数 (RUT)​ - 2000家小型公司组成的指数

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

• ​盘前交易​: 4:00 AM - 9:30 AM
• ​常规交易​: 9:30 AM - 4:00 PM
• ​盘后交易​: 4:00 PM - 8:00 PM

主要行业板块

• ​科技股​ - Apple (AAPL), Microsoft (MSFT), Google (GOOGL)
• ​金融股​ - JPMorgan Chase (JPM), Bank of America (BAC)
• ​医疗保健​ - Johnson & Johnson (JNJ), Pfizer (PFE)
• ​消费品​ - Procter & Gamble (PG), Coca-Cola (KO)
• ​能源股​ - Exxon Mobil (XOM), Chevron (CVX)

注意事项

1. ​API密钥申请​：需要联系API服务提供商获取有效的API密钥
2. ​交易时间​：注意美股交易时间（美国东部时间）和夏令时调整
3. ​货币单位​：美股价格以美元(USD)为单位
4. ​数据延迟​：实时数据可能有15分钟延迟（除非使用实时数据订阅）
5. ​请求限制​：注意API的请求频率限制，避免过于频繁的请求
6. ​错误处理​：添加适当的错误处理机制和重试逻辑

常见问题

​​Q: 如何获取实时数据而不是延迟数据？​ ​ A: 需要订阅实时数据服务，通常需要额外付费 ​​Q: 是否提供期权和期货数据？​ ​ A: 部分API提供商支持期权和期货数据，需要查看具体API文档 ​​Q: 如何获取财务报表数据？​ ​ A: 需要通过公司信息接口或专门的财务数据API获取 ​​Q: 数据更新频率是多少？​​ A: 实时数据通常每秒更新多次，具体取决于数据源和订阅级别

总结

通过本文介绍的API接口，开发者可以轻松获取美国股票市场的实时行情、历史数据和其他相关信息。美股作为全球最重要的金融市场，其数据对于全球投资者具有重要参考价值。无论是个人投资者还是金融机构，都可以利用这些API构建专业的股市分析系统。

---

​​版权声明​​：本文涉及API接口由相应服务商提供，使用前请确保已获得合法授权。本文仅做技术交流用途，不构成任何投资建议。股市投资有风险，投资需谨慎。