群益API 歷史 K 線怎麼取？兩個請求函式的差別與解析要點

想要 5 分 K，查了官方文件，看到一句「目前僅提供1分鐘K」，於是開始寫聚合程式。

這句話是真的，但它只描述了其中一個函式。群益API 歷史 K 線有兩個請求函式，能力不一樣。 先選對函式，有些事就不用自己做。

群益API 歷史 K 線有哪兩個請求函式？能力不一樣

開頭那句「目前僅提供1分鐘K」，出自 RequestKLineAM 的官方備註，完整的一句是：

目前僅提供1分鐘K，其他5分鐘、30分鐘K Line可自行以1分鐘K Line為基礎組成，目前未提供288日K Line。

這句只描述 RequestKLineAM。 另一個函式 RequestKLineAMByDate 有一個 sMinuteNumber 參數，官方說明是：

指定幾分K (ex : 1=1分K, 3=3分K)

所以要其他分鐘數的 K 線，先看 RequestKLineAMByDate。要注意的是，官方只舉了 1 與 3 兩個例子；sMinuteNumber 可以填到多大、每個值是否都可用，我們沒有實測過。 我們自己的實作是取 1 分 K 再自行聚合。

兩個函式有一個共同點：官方說明的開頭都是「（僅提供歷史資料）」。資料都從 OnNotifyKLineData 事件送來，以 OnKLineComplete 表示送完。盤中要即時更新的 K 棒怎麼跟歷史接起來，見〈群益API 即時 K 線怎麼接上歷史 K〉。

（V2.13.59 起，官方另外新增了即時分 K，會隨 RequestTicks 由 OnNotifyLiveKLineData 送來，只涵蓋當日。本文不展開。）

sOutType 選舊版還是新版？差在價格有沒有處理過小數

sOutType 決定輸出格式：0 是舊版、1 是新版。兩者的差別不只是日期寫法：

官方對舊版價格舉的例子是：價格為「36.50」，傳回的是「3650」。這就是〈群益API 報價價格為什麼是整數〉講的整數價格，要自己換算。官方另外提到，期匯率商品（TypeNo=209）小數有四位，須特別處理。

我們的建議是用新版，少一步換算；官方沒有說哪一版比較好。

sOutType 要傳整數

這裡有一個要注意的地方：RequestKLineAM 的官方宣告把 sOutType 寫成 BSTR（字串），V2.13.59 的主手冊也還是這樣寫；但我們讀取本機已註冊的元件型別庫，這個參數是 short（整數），跟 RequestKLineAMByDate 一致。

程式碼請照元件實際的型別，傳整數。 照官方宣告傳字串，型別就跟元件不一致。

群益API 歷史 K 線怎麼解析？欄數不要寫死

新版 1 分鐘線的官方格式說明是：

(年/月/日, 時:分, 開盤價, 最高價, 最低價, 收盤價, 成交量)

日期與時間之間是逗號。但官方給的例子是（節錄）：

2021/8/2 09:01

日期與時間之間是空格。

說明和例子對不上，所以解析時兩種都要能接受：先判斷這一列有幾個欄位，再決定日期與時間怎麼取，不要假設每個欄位的起點固定。

另外兩個防禦性做法：

• 每一次事件送來的字串，先按換行拆開再逐列解析。 就算一次只有一列，這樣做也不會壞。
• 數字用不受地區設定影響的格式解析。 這一點在〈群益API 下單價格為什麼是字串〉講過，同樣適用於解析。

什麼時候才算送完？等 OnKLineComplete

OnKLineComplete 的官方說明是：

收完歷史KLine，等收到此事件通知後表示回補完成。

它的參數 bstrEndString 是結尾字串「##」。

所以收到 OnKLineComplete 之後，才把 K 線交給後續的計算或畫面；在它之前收到的，都還只是一部分。

這個模式你可能已經見過：〈群益API 下單初始化有哪 7 步〉的回報通道要等 OnComplete，〈群益API Tick 回補是什麼〉的成交明細也會先回補。先送一批，再告訴你送完了。

全盤 K 線為什麼有前一天晚上的 K 棒？

sTradeSession 的官方說明是「僅國內期權技術分析有效。」，0 是全盤、1 是 AM 盤。官方對全盤給的例子是：

2023/9/5全盤K LINE，將包含2023/9/4 17:25開盤後~2023/9/5 05:00，及2023/9/5 8:45~16:15。

也就是說，某一天的全盤 K 線，包含前一天晚上開盤後的夜盤。 看到前一天晚上的 K 棒出現在今天的全盤資料裡，是這個原因。

⚠️ 這個例子是用來說明日期歸屬的，不要從例子裡的時間去推交易時段。各商品的交易時段，請以臺灣期貨交易所的公告為準。

查加權指數回 9999 是程式寫錯了嗎？

不一定。9999 的常數是 SK_FAIL。官方在報價方面對這個錯誤碼的說明，指向帳戶側的前置條件——屬帳戶設定範疇，不是程式端能解決的。

我們遇到過一次：對加權指數 TSEA 請求歷史 K 線回 9999，而同一個代碼的即時報價訂閱是通的。那一次是不是這個原因，我們沒有查證。

如果有遇到這類的問題可以先跟您的營業員反應。

群益API 歷史 K 線的 7 條做法＋程式碼

1. 要其他分鐘數，先看 RequestKLineAMByDate 的 sMinuteNumber；RequestKLineAM 只給 1 分 K。
2. 用新版輸出格式（sOutType = 1），價格已處理過小數；用舊版就要自己換算。
3. sOutType 照元件實際型別傳整數。
4. 解析時先看欄數，日期與時間同欄或分欄都要能接受；每次事件的字串先按換行拆。
5. 收到 OnKLineComplete 才算送完。
6. 全盤 K 線包含前一晚的夜盤。
7. 請求在連線就緒（3003）之後才送，見〈群益API 連線狀態碼怎麼解讀〉。

// 取 2025/10/01～2025/10/10 的 3 分 K（新版格式、全盤）
// sOutType 在元件型別庫是 short，官方宣告寫 BSTR，請以元件為準
// 3 分 K 是官方參數說明的例子；大於 1 的值我們沒有實測
int nCode = m_pSKQuote.SKQuoteLib_RequestKLineAMByDate(
    "YOUR_STOCK_NO", 0 /* 分線 */, 1 /* 新版 */, 0 /* 全盤 */,
    "20251001", "20251010", 3 /* 3 分 K */);

List<string> _rows = new List<string>();

void OnNotifyKLineData(string bstrStockNo, string bstrData)
{
    // 先按換行拆，一列也不會壞
    foreach (var row in bstrData.Split(new[] { '\r', '\n' }, StringSplitOptions.RemoveEmptyEntries))
        _rows.Add(row);
}

void OnKLineComplete(string bstrEndString)
{
    // 收到完成事件才開始解析；欄數不寫死：日期與時間可能同欄（空格）或分欄（逗號）
    foreach (var row in _rows) ParseKLineRow(row);
}

商品代號用佔位符，日期只是示意。事件在元件自己的執行緒上觸發，實際使用 _rows 時要注意同步，見〈群益API 事件回呼跑在哪個執行緒〉。

常見問題

風險揭露

期貨與選擇權屬高槓桿商品，價格波動可能造成超過原始保證金的損失，交易人須自負交易責任。本文為程式開發技術教學，說明歷史 K 線資料的取得與解析，不構成投資建議，也不保證任何交易結果。歷史資料不代表未來走勢；程式化交易並不降低市場風險，解析錯誤或資料未收完就開始計算，都可能讓程式依據不完整或錯誤的資料運作。

投資人教育資源

延伸閱讀

• 〈群益API 報價價格為什麼是整數〉——舊版輸出格式的整數價格怎麼換算。
• 〈群益API Tick 回補是什麼〉——盤中的即時資料，以及「先送一批再告訴你送完」的另一個例子。
• 〈群益API 連線狀態碼怎麼解讀〉——請求要在 3003 之後才送。
• 〈群益API 下單價格為什麼是字串〉——數字與字串轉換時的地區設定問題。

參考資料

• SKQuoteLib_RequestKLineAM、SKQuoteLib_RequestKLineAMByDate 的說明、參數與備註，OnNotifyKLineData 的四種輸出格式，OnKLineComplete 的說明，依群益官方元件說明文件「國內報價」章節；9999 依官方錯誤代碼表；即時分 K 依 V2.13.59 主手冊。
• sOutType 的實際型別：讀取本機已註冊的元件型別庫。
• 1 分 K 自行聚合、解析時的欄數容錯與換行拆列、TSEA 回 9999 的經驗：實作與實測經驗，非官方文件記載。

免責聲明

本文章僅作為群益API實作經驗分享，不構成投資建議，且策略及程式皆應自行撰寫。期貨及衍生性金融商品交易屬高風險投資，請謹慎評估自身風險承擔能力。