本接口提供日本東京證券交易所（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
• 關鍵參數:

• 請求示例:

<!-- end list -->

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

• 響應示例:

<!-- end list -->

{
  "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
• 關鍵參數:

• 請求示例:

<!-- end list -->

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

2.3 獲取 K 線數據 (Candlestick/Kline)

獲取指定股票的歷史價格數據，用於繪製 K 線圖。

• 接口地址: /stock/kline
• 請求方式: GET
• 關鍵參數:

• 週期 (Interval) 枚舉值:

  • PT1M (1分鐘)
  • PT5M (5分鐘)
  • PT1H (1小時)
  • P1D (日K)
  • P1W (周K)
  • P1M (月K)
• 響應示例:

<!-- end list -->

{
  "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
• 推送數據格式:

<!-- end list -->

{
    "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');