日本股票数据接口集成文档 股票数据源API

本接口提供日本东京证券交易所（TSE）及相关市场的实时行情、历史 K 线及指数数据。所有接口均基于 HTTP/HTTPS 协议，返回 JSON 格式数据。

• API Base URL: https://api.stocktv.top
• WebSocket URL: wss://ws-api.stocktv.top/connect
• 认证方式: URL 参数 key
• 日本市场 ID (Country ID): 35

---

2. 核心接口说明

2.1 获取日本股票列表 (Market List)

用于获取日本市场的股票列表，包括股票名称、代码 (Symbol) 和系统内部 ID (PID)。PID 是后续查询 K 线和具体行情的关键参数。

• 接口地址: /stock/stocks
• 请求方式: GET
• 关键参数:

参数名	类型	必填	示例值	说明
key	String	是	您的API密钥	鉴权 Key
countryId	Int	是	35	日本的国家 ID
pageSize	Int	否	20	每页数量
page	Int	否	1	页码

• 请求示例:

GET https://api.stocktv.top/stock/stocks?countryId=35&pageSize=20&page=1&key=YOUR_KEY

• 响应示例:

{
  "code": 200,
  "data": {
    "records": [
      {
        "id": 953373,          // [重要] PID，用于K线接口
        "name": "Toyota Motor",// 公司名称
        "symbol": "7203",      // 股票代码
        "last": 3150.0,        // 最新价
        "chgPct": 1.5,         // 涨跌幅%
        "volume": 500000       // 成交量
      }
    ]
  }
}

---

2.2 获取日本市场指数 (Indices)

获取日经 225 (Nikkei 225)、TOPIX 等主要指数的实时行情。

• 接口地址: /stock/indices
• 请求方式: GET
• 关键参数:

参数名	类型	必填	示例值	说明
key	String	是	您的API密钥	-
countryId	Int	是	35	日本

• 请求示例:

GET https://api.stocktv.top/stock/indices?countryId=35&key=YOUR_KEY

---

2.3 获取 K 线数据 (Candlestick/Kline)

获取指定股票的历史价格数据，用于绘制 K 线图。

• 接口地址: /stock/kline
• 请求方式: GET
• 关键参数:

参数名	类型	必填	示例值	说明
key	String	是	您的API密钥	-
pid	Int	是	953373	通过 2.1 接口获取的股票 ID
interval	String	是	P1D	K线周期 (ISO 8601格式)

• 周期 (Interval) 枚举值:

  • PT1M (1分钟)
  • PT5M (5分钟)
  • PT1H (1小时)
  • P1D (日K)
  • P1W (周K)
  • P1M (月K)

• 响应示例:

{
  "code": 200,
  "data": [
    {
      "time": 1719818400000, // 时间戳 (毫秒)
      "open": 3100.0,        // 开盘
      "high": 3160.0,        // 最高
      "low": 3090.0,         // 最低
      "close": 3150.0,       // 收盘
      "volume": 45000        // 成交量
    }
  ]
}

---

2.4 WebSocket 实时推送

建立长连接，实时接收日本股票的价格跳动。

• 连接地址: wss://ws-api.stocktv.top/connect?key=YOUR_KEY
• 推送数据格式:

{
    "pid": "953373",      // 产品ID
    "last_numeric": 3155, // 最新成交价
    "bid": 3154,          // 买一价
    "ask": 3156,          // 卖一价
    "timestamp": "1717728251", // 时间戳
    "pcp": "1.25"         // 涨跌幅
}

---

3. 常见问题 (FAQ)

Q1: 如何查找特定代码（如 7203 Toyota）的数据？

A: 目前接口不支持直接通过 Symbol（如 7203）请求 K 线。流程是：先调用 /stock/stocks?countryId=35，在返回列表中遍历匹配 symbol="7203"，获取其对应的 id (PID)，再使用该 PID 调用 K 线接口。

Q2: 为什么 K 线数据的时间戳是乱序的？

A: 接口偶尔可能返回非严格排序的数据。建议前端在接收数据后，根据 time 字段进行一次升序排序 (sort((a,b) => a.time - b.time)) 再渲染图表。

Q3: K 线接口支持分页吗？

A: /stock/kline 接口目前是一次性返回指定周期内的近期数据，不支持分页参数。

---

4. 接入代码示例 (JavaScript/Fetch)

const API_KEY = 'YOUR_API_KEY';
const JAPAN_ID = 35;

async function getJapanStockData(symbolCode) {
    // 1. 获取股票列表并查找 PID
    const listRes = await fetch(`https://api.stocktv.top/stock/stocks?countryId=${JAPAN_ID}&pageSize=100&key=${API_KEY}`);
    const listData = await listRes.json();
    
    // 查找指定代码 (例如 '7203')
    const targetStock = listData.data.records.find(stock => stock.symbol === symbolCode);
    
    if (!targetStock) {
        console.error('未找到该股票');
        return;
    }

    console.log(`找到股票: ${targetStock.name}, PID: ${targetStock.id}`);

    // 2. 获取 K 线数据 (日线)
    const klineRes = await fetch(`https://api.stocktv.top/stock/kline?pid=${targetStock.id}&interval=P1D&key=${API_KEY}`);
    const klineData = await klineRes.json();

    console.log('K线数据:', klineData.data);
}

// 调用示例：获取 7203 (丰田) 数据
getJapanStockData('7203');