群益API 即時分K怎麼用?GetLiveKLineLONG 與 OnNotifyLiveKLineData 的 Python 寫法
以前要在盤中拿到每分鐘的 K 棒,只能自己用 Tick(逐筆成交)聚合。元件 2.13.59 起,官方新增了即時分K,但照著手冊找訂閱函式,卻找不到;掛上事件後,同一分鐘又收到一大串資料,其中還有一筆價格全是 0。
使用群益API 即時分K,可以先記住三件事:沒有獨立的訂閱函式,即時分K隨 RequestTicks 一起送來;同一個事件裝了三種資料,要先看 nType;價格和時間都是整數,要自己還原。
本文以官方元件說明文件 V2.13.59 為主。Python 呼叫的部分,是我們在 SKCOM 2.13.59 x64、Python 3.12、comtypes 1.4.16、未登入狀態下實際呼叫的結果。我們沒有在登入狀態下收過即時分K,所以登入後事件實際長什麼樣,本文只列出官方沒有說明的地方,不寫猜測的答案。

目錄
群益API 即時分K是什麼?2.13.59 新增了哪些東西
官方版本控管表裡,2026/08/03 發行的 2.13.59 在「功能新增」列了一行:「即時分K SKQuoteLib_GetLiveKLineLONG」。配套的事件與結構,一併出現在 V2.13.59 的官方手冊裡:
函式(主動取一次):
Long SKQuoteLib_GetLiveKLineLONG([in] BSTR bstrStockNo, [in,out] struct SKKLINE* pSKKLine);事件(元件推送):
void OnNotifyLiveKLineData([in] LONG nType, [in] BSTR bstrStockNo, [in] LONG nDate, [in] LONG nTimehm, [in] LONG nOpen, [in] LONG nHigh, [in] LONG nLow, [in] LONG nClose, [in] LONG nQty);結構(官方手冊 5-26「國內報價KLINE物件」):
struct SKKLINE
{
LONG nDate;//交易日(YYYYMMDD)
LONG nTimehm;//成交時間HHmm (Ex: 904,代表09點04分)
LONG nOpen;//開盤價
LONG nHigh;//最高價
LONG nLow;//最低價
LONG nClose;//目前價
LONG nQty;//目前量
};舊版元件沒有這個函式。 先確認手上的元件版本:SKCenterLib_GetSKAPIVersionAndBit 要帶一個帳號參數,回傳版本字串,我們的環境回 2.13.59_x64。
print(center.SKCenterLib_GetSKAPIVersionAndBit("YOUR_ID"))版本不夠新,換元件的注意事項見〈群益API 版本升級要注意什麼〉。
群益API 即時分K要怎麼訂閱?
沒有獨立的訂閱函式,入口就是 RequestTicks。 官方手冊 4-4-3 SKQuoteLib_RequestTicks 的說明寫:
訂閱要求傳送成交明細、五檔、即時分K(包含當日分K回補)、該分鐘每筆Tick更新一次分K。
同一節的「相關通知事件」寫:
即時分K(包含當日分K回補)及該分鐘每筆Tick更新一次分K由OnNotifyLiveKLineData事件通知。
手冊 4-4-35 括號裡提到 RequestLiveKLine,但 2.13.59 元件裡沒有這個函式;照 4-4-3,用 RequestTicks 訂閱即可。
所以做法是:掛上 OnNotifyLiveKLineData,對商品呼叫 RequestTicks,即時分K就會跟著成交明細、五檔一起來。
page_no, code = quote.SKQuoteLib_RequestTicks(0, "TX00") # 即時分K隨 RequestTicks 一起來訂閱前要先做到兩件事:
- 用
EnterMonitorLONG連上報價。 官方事件說明寫「須使用SKQuoteLib_EnterMonitorLONG登入,該事件才會被觸發」。 - 等
OnConnection收到 3003 再訂閱,見〈群益API 連線狀態碼怎麼解讀〉。
另外要知道:成交明細與五檔也會一起送來。 官方寫明 RequestTicks 會一併送出成交明細與五檔,它屬於報價訂閱裡含成交明細與五檔的那一層,見〈群益API 報價訂閱有哪兩層〉。
額度方面,官方沒有另外寫即時分K的檔數限制。因為入口就是 RequestTicks,所以我們推論:想看幾檔(幾個商品代號)的即時分K,就會佔幾檔 RequestTicks 的額度。這一點我們沒有實測,額度本身見〈群益API 訂閱額度有多少〉。
RequestTicks 的第一個參數是頁號,方向是 [in,out](既要傳入,也會傳回),所以呼叫時要傳一個值,comtypes 會把頁號和回傳碼一起放進 list 傳回;這是 comtypes 的規則,見〈群益API Python 回傳值為什麼是 list〉。
OnNotifyLiveKLineData 的 nType 是什麼?0、1、2 各代表一種資料
三種資料都走同一個事件。官方手冊對 nType 參數的說明:
0:資料重置,需要捨棄目前已收到資料 ,本筆資料價格都給 0 (清盤通知)1:即時分K(包含回補當日分K)2:該分鐘每筆Tick
同一節的備註:
nType = 1,會先收到當日回補分K,並且訂閱即時分K(1分鐘給一次) nType = 2,僅訂閱即時分K(該分鐘每筆Tick)
整理成表:
| nType | 官方說明 | 程式怎麼處理 |
|---|---|---|
| 0 | 資料重置,本筆價格都給 0(清盤通知) | 丟掉已收的資料;這一筆本身不是 K 棒 |
| 1 | 即時分K,先收到當日回補,之後 1 分鐘給一次 | 當成每分鐘一筆的分K記下來 |
| 2 | 該分鐘每筆 Tick 更新一次分K | 當成「這一分鐘目前的樣子」;本文範例用新的一筆蓋掉舊的 |
三個要注意的地方:
- 每來一筆都當成一根 K 棒,就會出錯。 每筆 Tick 的更新、甚至清盤那筆全是 0 的資料,都會被當成 K 棒。要先看
nType。 - 備註裡的「訂閱」兩個字,我們解讀為兩種資料,不是兩種訂閱選項。 讀起來像是可以選擇訂 1 或訂 2,但沒有任何函式帶
nType參數,RequestTicks只有頁號與商品代號兩個參數。所以我們認為這兩行是在說明事件會送來哪兩種資料,不是讓你選擇要訂哪一種。 nType = 0要捨棄的範圍,官方沒有寫是這一檔還是全部。事件有帶商品代號bstrStockNo,本文範例只清這一檔商品的資料。
群益API 即時分K的價格與時間怎麼還原?
官方手冊的事件備註寫:
*請注意價格為原始價格,需自行除以小數位數還原價格, 例如:收到群益證為3815,需自行處理成38.15 ;收到台指期為4557900,需自行處理成45579.00
- 價格:官方的兩個例子都是除以 100。官方沒有指名要用哪個欄位的小數位數;我們的做法是用國內商品結構
SKSTOCKLONG的sDecimal(小數位數),除以 10 的sDecimal次方,與官方的兩個例子一致。sDecimal怎麼取,見〈群益API 報價價格為什麼是整數〉。 - 時間:
nTimehm是 HHmm(時兩位、分兩位)的整數,904代表 09:04。轉成字串要補零,否則會得到"904"而不是"0904"。 - 日期:
nDate是 YYYYMMDD 的整數。
計算用原始整數,顯示時才換算,可以避免浮點誤差。
GetLiveKLineLONG 怎麼呼叫?Python 為什麼回傳 list
GetLiveKLineLONG 是主動取一次,不必等事件。官方手冊的備註有兩句:
避免在OnNotifyLiveKLineData通知事件裡進行SKQuoteLib_GetLiveKLineLONG。 *須使用SKQuoteLib_EnterMonitorLONG登入,方可執行此函式。
官方的用字是「避免」。事件裡只收集,取值放到主迴圈,這跟事件回呼的一般紀律是同一個原則,見〈群益API 事件回呼跑在哪個執行緒〉。
pSKKLine 這個參數是 [in,out],所以 comtypes 回傳的是 list:[SKKLINE 物件, 回傳碼]。直接拆包:
# 在主迴圈呼叫;官方建議避免在 OnNotifyLiveKLineData 裡呼叫
k, code = quote.SKQuoteLib_GetLiveKLineLONG("TX00", sk.SKKLINE())
# code 為 0 才讀 k.nDate、k.nTimehm、k.nClose 等欄位;價格還要除以 10 的 sDecimal 次方我們在未登入狀態實際呼叫的結果:
- 回傳一個 list,長度為 2,第一個元素是
SKKLINE物件,第二個元素是1000。 - 不傳結構,寫成
quote.SKQuoteLib_GetLiveKLineLONG("TX00")也可以,comtypes 會自動補一個,回傳的形態相同。 1000是SK_ERROR_LOGIN_FIRST,官方說明是「請先由Center 進行登入動作 *請注意登入帳號是否為大寫」。
官方沒有說明 GetLiveKLineLONG 取回的是哪一根:最新一根,還是最後一根已經結束的。結構只裝得下一根,參數也沒有時間或索引。登入後的回傳內容,我們沒有實測。
群益API 即時分K Python 範例:事件只收集,主迴圈依 nType 分流
前提是已經登入、用 EnterMonitorLONG 連上報價、收到 3003,事件類別在登入前就掛好,主迴圈持續抽取訊息。這些步驟見〈群益API Python 入門〉。
inbox = [] # 事件收到的資料先放這裡
bars = {} # 每分鐘一筆的分K:(商品, 日期, HHmm) -> (開, 高, 低, 收, 量)
live = {} # 這一分鐘還在變動的分K
class QuoteEvents:
def OnNotifyLiveKLineData(self, nType, bstrStockNo, nDate, nTimehm,
nOpen, nHigh, nLow, nClose, nQty):
inbox.append((nType, bstrStockNo, nDate, nTimehm,
nOpen, nHigh, nLow, nClose, nQty)) # 事件裡只收集
page_no, code = quote.SKQuoteLib_RequestTicks(0, "TX00") # 即時分K隨 RequestTicks 一起來
def drain(): # 在主迴圈呼叫
while inbox:
nType, stock, d, hm, o, h, l, c, q = inbox.pop(0)
if nType == 0: # 清盤:這檔已收的資料全部丟掉
for book in (bars, live):
for key in [k for k in book if k[0] == stock]:
del book[key]
elif nType == 1: # 1 分鐘一次,含當日回補
bars[(stock, d, hm)] = (o, h, l, c, q)
elif nType == 2: # 該分鐘每筆 Tick 更新一次
live[(stock, d, hm)] = (o, h, l, c, q)這段範例我們在未登入狀態下手動呼叫事件方法,模擬三種 nType、兩檔商品,確認分流結果符合預期。登入後真正的事件內容沒有驗證過。
兩點補充:
live只增不減。 範例以(商品, 日期, HHmm)當鍵,長時間執行會一直累積,實際程式要定期清掉舊的分鐘。- 價格存的是原始整數。 顯示時再除以 10 的
sDecimal次方,nTimehm補零成四位。
群益API 即時分K有哪些事官方手冊沒有說明?
以下各項,我們查過官方手冊的相關章節與結構定義,也用關鍵字搜尋過全文,都找不到說明;我們也沒有在登入狀態下測過。第一次使用時,建議先在主迴圈把收到的九個參數原樣印出來,自己確認。
- 事件實際的到達順序與頻率,例如回補的分K與即時的 Tick 更新會不會交錯。
- 同一分鐘的
nType = 2與nType = 1,最後的數值是否一致。 nTimehm是 K 棒的起點還是終點。官方欄位說明只有「成交時間HHmm」。這跟〈群益API 即時 K 線怎麼接上歷史 K〉提過的時間標籤問題是同一件事。- 夜盤跨過午夜之後,
nDate是哪一天。官方的用字有兩個:結構寫「交易日(YYYYMMDD)」,事件寫「日期YYYYMMDD」,兩處都沒有說明夜盤的情況。 nQty是這一分鐘累計的量,還是最後一筆的量。官方欄位說明只有「目前量」。- 清盤(
nType = 0)在什麼時候發生。 - 呼叫
CancelRequestTicks之後,即時分K會不會一起停。官方手冊 4-4-22 只寫「取消訂閱RequestTicks的成交明細及五檔。」,沒有提到即時分K。
另外一項,官方有寫的部分和沒寫的部分要分開看:
EnterMonitorLONGByMarket(2.13.59 新增的連線函式)。官方有寫的:它可以指定只訂國內證券市場或只訂國內期貨市場,與EnterMonitorLONG擇一使用;而即時分K的事件說明寫,要用EnterMonitorLONG登入,事件才會觸發。官方沒有寫的:改用EnterMonitorLONGByMarket連線時,即時分K會不會來。
群益API 即時分K有哪些官方限制?
官方手冊的事件備註寫明:
不支援盤中零股。 證券:該查詢以整股為主計算,不包含「鉅額交易、盤中零股、盤後零股」 不支援價差商品。
回補的範圍,官方寫的是當日分K(4-4-3「包含當日分K回補」、事件說明「回補當日分K」),沒有提到更早的日期。要跨多日的歷史分K,請用歷史 K 線函式,見〈群益API 歷史 K 線怎麼取〉。
群益API 即時分K的 4 個誤解
- 誤解:
OnNotifyLiveKLineData每來一筆就是一根 K 棒。其實: 同一個事件裝了三種資料,nType = 2是這一分鐘每筆 Tick 的更新,nType = 0是清盤通知、價格全是 0。 - 誤解: 有了即時分K,就可以不訂 Tick。其實: 入口就是
RequestTicks,官方寫明它會一併送出成交明細與五檔。 - 誤解: 即時分K可以拿來補歷史。其實: 官方寫的回補範圍是當日分K,跨日請用歷史 K 線函式。
- 誤解:
GetLiveKLineLONG回傳的是回傳碼。其實: comtypes 回傳[SKKLINE 物件, 回傳碼]這個 list,要拆包。
常見問題
OnNotifyLiveKLineData 每一筆都是一根 K 棒嗎?
不是。先看 nType:1 是每分鐘一筆的分K(含當日回補);2 是這一分鐘每筆 Tick 的更新;0 是清盤通知,價格都給 0,這一筆本身不是 K 棒。
用即時分K,可以不訂 Tick 嗎?
不行。即時分K的入口就是 RequestTicks,官方寫明它會一併送出成交明細與五檔。我們的推論是:想看幾檔的即時分K,也要佔幾檔 RequestTicks 的額度;這一點官方沒有另外寫,我們也沒有實測。
即時分K可以補過去幾天的分K嗎?
官方寫的回補範圍是當日分K,沒有提到更早的日期。跨多日的歷史分K,請用 RequestKLineAMByDate 這類歷史 K 線函式。
GetLiveKLineLONG 回傳 1000 是什麼意思?
意思是還沒登入。1000 是 SK_ERROR_LOGIN_FIRST,官方說明是「請先由Center 進行登入動作 *請注意登入帳號是否為大寫」。官方也寫明,要先用 EnterMonitorLONG 登入報價,才可以執行這個函式。
風險揭露
期貨與選擇權屬高槓桿商品,價格波動可能造成超過原始保證金的損失,交易人須自負交易責任。本文為程式開發技術教學,說明 Python 呼叫群益API 即時分K的方式,不構成投資建議,也不保證任何交易結果。程式化交易並不降低市場風險,K 棒資料判讀錯誤可能讓程式依錯誤的數值運作,正式使用前請充分測試。
投資人教育資源
| 機構 | 資源 |
|---|---|
| 臺灣期貨交易所(TAIFEX) | 期貨及選擇權數位學習網 |
| 證券暨期貨市場發展基金會 | 證券期貨市場教育推廣 |
| 金融智慧網 | 金管會金融知識平台 |
| 中華民國期貨業商業同業公會 | 期貨業法規與宣導 |
| 證券投資人及期貨交易人保護中心 | 投資人保護與申訴 |
延伸閱讀
- 〈群益API Python 入門〉——登入、掛事件、主迴圈抽取訊息。
- 〈群益API 歷史 K 線怎麼取〉——跨日的歷史分K。
- 〈群益API 即時 K 線怎麼接上歷史 K〉——K 棒接縫與時間標籤。
- 〈群益API 報價價格為什麼是整數〉——sDecimal 與整數時間的換算。
參考資料
SKQuoteLib_GetLiveKLineLONG、OnNotifyLiveKLineData、SKKLINE、SKQuoteLib_RequestTicks、SKQuoteLib_CancelRequestTicks、SKQuoteLib_EnterMonitorLONGByMarket的宣告與說明,以及版本控管表、錯誤碼 1000,依群益官方元件說明文件 V2.13.59。- comtypes – PyPI
- 回傳形態(list)、結構可省略、未登入回 1000、範例的分流結果:我們 2026-11-07 在 SKCOM 2.13.59 x64、comtypes 1.4.16、未登入狀態的實測,非官方文件記載。登入後的事件內容我們沒有實測。
免責聲明
本文章僅作為群益API實作經驗分享,不構成投資建議,且策略及程式皆應自行撰寫。期貨及衍生性金融商品交易屬高風險投資,請謹慎評估自身風險承擔能力。







