版本遷移指南

本文件將引導您將現有的行情 API v0.3 版本升級至最新的 v1.0 版本。

主要差異

行情 v0.3 API

API 端點：

GET /realtime/v0.3/intraday/meta - 取得個股/指數當日基本資訊
GET /realtime/v0.3/intraday/quote - 取得個股/指數逐筆交易金額、狀態、統計資訊
GET /realtime/v0.3/intraday/chart - 個股/指數線圖時所需的各項即時資訊
GET /realtime/v0.3/intraday/dealts - 取得個股當日所有成交資訊
GET /realtime/v0.3/intraday/volumes - 提供盤中個股即時分價量

其中，Meta、Quote、Chart 提供 WebSocket 介面，使用者可以即時接收行情資料。

行情 v1.0 API

在 v1.0 版本中，目前提供股票行情，URL 位址如下：

https://api.fugle.tw/marketdata/v1.0/stock/

API 端點：

GET /intraday/tickers - 股票或指數列表（依條件查詢）
GET /intraday/ticker/{symbol} - 股票基本資料（依代碼查詢）
GET /intraday/quote/{symbol} - 股票即時報價（依代碼查詢）
GET /intraday/candles/{symbol} - 股票價格Ｋ線（依代碼查詢）
GET /intraday/trades/{symbol} - 股票成交明細（依代碼查詢）
GET /intraday/volumes/{symbol} - 股票分價量表（依代碼查詢）
GET /snapshot/quotes/{market} - 股票行情快照（依市場別）
GET /snapshot/movers/{market} - 股票漲跌幅排行（依市場別）
GET /snapshot/actives/{market} - 股票成交量值排行（依市場別）
GET /historical/candles/{symbol} - 取得 1 年內歷史股價（依代碼查詢）
GET /historical/stats/{symbol} - 取得近 52 週股價數據（依代碼查詢）

在 v1.0 版本中，WebSocket API 採用訂閱頻道機制，您可以現在透過 WebSocket 連線管理訂閱，接收特定股票及指數的行情資訊。WebSocket 連線位址如下：

wss://api.fugle.tw/marketdata/v1.0/stock/streaming

WebSocket API v1.0 提供以下頻道類型可供訂閱：

trades - 接收訂閱股票最新成交資訊
candles - 接收訂閱股票最新分鐘Ｋ
books - 接收訂閱股票最新最佳五檔委買委賣資訊
aggregates - 接收訂閱股票聚合數據的行情資訊

遷移流程

身份驗證

在行情 API v1.0 版本中，我們採用了不同的身份驗證方式，因此 v0.3 的 API 金鑰將無法適用於 v1.0 的 HTTP API 和 WebSocket API。您需要重新申請 API 金鑰以使用最新版本的 API。請前往金鑰申請頁面進行申請。

富果行情 API v1.0 版本使用 API 金鑰進行用戶身份驗證。請在發送 API 請求時，加入以下的 HTTP 標頭（Header）：

X-API-KEY: <YOUR_API_KEY>

若使用 WebSocket API，請在建立 WebSocket 連線後，傳送以下訊息進行 API 金鑰驗證以獲得訂閱各項頻道的授權：

{
  "event": "auth",
  "data": {
    "apikey": "<API_KEY>"
  }
}

版本資料對應

行情 v1.0 版本提供了更豐富的市場資料。根據資料性質，在 v0.3 版本的基礎上，可以做以下對應轉換：

v0.3 的 Meta 對應到 v1.0 的 Ticker v0.3 的 Quote 對應到 v1.0 的 Quote v0.3 的 Chart 對應到 v1.0 的 Candles v0.3 的 Dealts 對應到 v1.0 的 Trades v0.3 的 Volumes 對應到 v1.0 的 Volumes

詳細內容請參考資料欄位對照表。

資料欄位對照表

v0.3 Meta／v1.0 Ticker

v0.3 Meta	v1.0 Ticker	備註
`info.date`	`date`
`info.type`	`type`
`info.exchange`	`exchange`
`info.market`	`market`
`info.symbolId`	`symbol`
`info.countryCode`	-	移除
`info.timeZone`	-	移除
`info.lastUpdatedAt`	-	移除
`meta.market`	`market`
`meta.nameZhTw`	`name`
`meta.industryZhTw`	`industry`	改為產業代碼
`meta.previousClose`	`previousClose`
`meta.priceReference`	`referencePrice`
`meta.priceHighLimit`	`limitUpPrice`
`meta.priceLowLimit`	`limitDownPrice`
`meta.canDayBuySell`	`canBuyDayTrade`	先買現沖
`meta.canDaySellBuy`	`canDayTrade`	買賣現沖
`meta.canShortMargin`	`canBelowFlatMarginShortSell`	平盤下得融券賣出
`meta.canShortLend`	`canBelowFlatSBLShortSell`	平盤下得借券賣出
`meta.tradingUnit`	`boardLot`
`meta.currency`	`tradingCurrency`
`meta.isTerminated`	-	以 `securityStatus` 取代
`meta.isSuspended`	-	以 `securityStatus` 取代
`meta.typeZhTw`	`securityType`
`meta.abnormal`	-	以 `isAttention`, `isDispostion` 取代
-	`isAttention`	注意股
-	`isDisposition`	處置股
`meta.isUnusuallyRecommended`	`isUnusuallyRecommended`	異常推介個股
`meta.isNewlyCompiled`	-	新編指數
-	`isSpecificAbnormally`	特殊異常個股
-	`securityStatus`	證券狀態，分別有 `NORMAL`, `TERMINATED`, `SUSPENDED` 狀態
-	`exercisePrice`	權證履約價格
-	`exercisedVolume`	權證前一營業日履約數量
-	`cancelledVolume`	權證前一營業日註銷數量
-	`remainingVolume`	權證發行餘額量
-	`exerciseRatio`	權證行使比率
-	`knockInPrice`	權證上限價格
-	`knockOutPrice`	權證下限價格
-	`maturityDate`	權證到期日
`meta.priceReference`	-	指數參考價，以 `previousClose` 取代
-	`previousClose`	指數前次收盤價
-	`openTime`	指數開盤時間
-	`closeTime`	指數收盤時間

v0.3 Quote／v1.0 Quote

v0.3 Quote	v1.0 Quote	備註
`info.date`	`date`
`info.type`	`type`
`info.exchange`	`exchange`
`info.market`	`market`
`info.symbolId`	`symbol`
`info.countryCode`	-	移除
`info.timeZone`	-	移除
`info.lastUpdatedAt`	`lastUpdated`	改為 timestamp 格式
`quote.isCurbing`	-	移除
`quote.isCurbingFall`	-	以 `isLimitDownHalt` 取代
`quote.isCurbingRise`	-	以 `isLimitUpHalt` 取代
`quote.isTrial`	`isTrial`
`quote.isOpenDelayed`	`isDelayedOpen`
`quote.isCloseDelayed`	`isDelayedClose`
-	`isContinuous`	是否為逐筆交易
-	`isOpen`	是否為開盤 tick
-	`isClose`	是否為收盤 tick
`quote.isHalting`	`tradingHalt.isHalted`	暫停交易
-	`tradingHalt.time`	暫停/恢復交易時間
`quote.isDealt`	-	`lastTrade.serial === serial`
`quote.isClosed`	-	參照 `isClose`
`quote.total.at`	`total.time`	改為 timestamp 格式
`quote.total.transaction`	`total.transaction`
`quote.total.tradeValue`	`total.tradeValue`
`quote.total.tradeVolume`	`total.tradeVolume`
`quote.total.tradeVolumeAtBid`	`total.tradeVolumeAtBid`
`quote.total.tradeVolumeAtAsk`	`total.tradeVolumeAtAsk`
`quote.total.bidOrders`	`total.bidOrders`	大盤總委買筆數
`quote.total.askOrders`	`total.askOrders`	大盤總委賣筆數
`quote.total.bidVolume`	`total.bidVolume`	大盤總委買數量
`quote.total.askVolume`	`total.askVolume`	大盤總委賣數量
`quote.total.serial`	-	移除
`quote.trial.at`	`lastTrial.time`	改為 timestamp 格式
`quote.trial.bid`	`lastTrial.bid`
`quote.trial.ask`	`lastTrial.ask`
`quote.trial.price`	`lastTrial.price`
`quote.trial.volume`	`lastTrial.size`
`quote.trial.serial`	`lastTrial.serial`
`quote.trade.at`	`lastTrade.time`	改為 timestamp 格式
`quote.trade.bid`	`lastTrade.bid`
`quote.trade.ask`	`lastTrade.ask`
`quote.trade.price`	`lastTrade.price`
`quote.trade.volume`	`lastTrade.size`
`quote.trade.serial`	`lastTrade.serial`
-	`lastPrice`	最近成交(試撮)價
-	`lastSize`	最近成交(試撮)單量
`quote.order.bids`	`bids`	`volume` 改 `size`
`quote.order.asks`	`asks`	`volume` 改 `size`
`quote.order.at`	-	參照 `lastUpdated`
`quote.priceHigh.price`	`highPrice`
`quote.priceHigh.at`	`highTime`	改為 timestamp 格式
`quote.priceLow.price`	`lowPrice`
`quote.priceLow.at`	`lowTime`	改為 timestamp 格式
`quote.priceOpen.price`	`openPrice`
`quote.priceOpen.at`	`openTime`	改為 timestamp 格式
`quote.priceAvg.price`	`avgPrice`
`quote.priceAvg.at`	-
`quote.change`	`change`
`quote.changePercent`	`changePercent`
`quote.amplitude`	`amplitude`
`quote.priceLimit`	-
-	`isLimitDownPrice`	最近成交價為跌停價
-	`isLimitUpPrice`	最近成交價為漲停價
-	`isLimitDownBid`	最佳一檔委買跌停價
-	`isLimitUpBid`	最佳一檔委買漲停價
-	`isLimitDownAsk`	最佳一檔委賣跌停價
-	`isLimitUpAsk`	最佳一檔委賣漲停價
-	`isLimitDownHalt`	暫緩撮合且瞬間趨跌
-	`isLimitUpHalt`	暫緩撮合且瞬間趨漲
-	`serial`

v0.3 Chart／v1.0 Candles

caution

v1.0 版本調整了Ｋ線的起迄時間設定。以分鐘Ｋ為例，09:00:00 ~ 9:00:59 這段時間的成交價格，在原 v0.3 Chart 計算在 09:01；v1.0 Candles 則計入 09:00。

v0.3 Chart	v1.0 Candles	備註
`info.date`	`date`
`info.type`	`type`
`info.exchange`	`exchange`
`info.market`	`market`
`info.symbolId`	`symbol`
`info.countryCode`	-	移除
`info.timeZone`	-	移除
`info.lastUpdatedAt`	-	移除
-	`timeframe`	Ｋ線週期
`chart`	`data`
`chart.t[0]`	`data[0].date`	改為 ISO 8601 格式
`chart.o[0]`	`data[0].open`
`chart.h[0]`	`data[0].high`
`chart.l[0]`	`data[0].low`
`chart.c[0]`	`data[0].close`
`chart.a[0]`	`data[0].average`
`chart.v[0]`	`data[0].volume`

Dealts / Trades

v0.3 Dealts	v1.0 Trades	Note
`info.date`	`date`
`info.type`	`type`
`info.exchange`	`exchange`
`info.market`	`market`
`info.symbolId`	`symbol`
`info.countryCode`	-	移除
`info.timeZone`	-	移除
`dealts[0].at`	`data[0].time`
`dealts[0].bid`	`data[0].bid`
`dealts[0].ask`	`data[0].ask`
`dealts[0].price`	`data[0].price`
`dealts[0].volume`	`data[0].size`
`dealts[0].serial`	`data[0].serial`
-	`data[0].volume`	成交總量

Volumes / Volumes

v0.3 Dealts	v1.0 Trades	備註
`info.date`	`date`
`info.type`	`type`
`info.exchange`	`exchange`
`info.market`	`market`
`info.symbolId`	`symbol`
`info.countryCode`	-	移除
`info.timeZone`	-	移除
`info.lastUpdatedAt`	-	移除
`volumes`	`data`

版本遷移指南

主要差異​

行情 v0.3 API​

行情 v1.0 API​

遷移流程​

身份驗證​

版本資料對應​

資料欄位對照表​