工具箱 / Agent 資料查詢
讓 Agent 查 GUYI 收錄的資料
適合已有 Agent、想取得個股名稱、相關主題、事件與新聞來源的人。這個入口回傳資料,不會呼叫 AI 模型,也不會替你下單。
先試查,再交給 Agent
選擇需要的資料後按「試查資料」,確認回傳內容、來源與資料時間,再複製 GET 網址。試查不產生 AI 回答,仍受公開查詢用量與次數限制。
正在準備試查表單,請稍候…
這次的 GET 網址
https://stock.luvai.net/api/v1/kb/query?q=2330&types=stocks&limit=5已帶入搜尋條件。請確認關鍵字與類別,再按「試查資料」。
需要股價與配息情境資料?
上方個股知識庫查詢只回傳基本資料,不提供股價。服務端 Agent 可使用既有 GET /api/tools/dividend-lookup?code=2330 取得 GUYI 已收錄的價格參考值與上一完整曆年現金配息合計;此查詢不呼叫 AI 模型或外部行情服務。
price_source 區分 quote 報價、daily 日收盤與 unavailable 缺少資料。price_date 為實際價格的台灣日期,報價另有毫秒時間 price_ts;日收盤的時間為 null,不能補成查詢時間。
dividend_target_year 是要查的完整年度;cash_dividend 為 null 表示未知,零表示已收錄合計為零。價格日期與配息年度分開保留,不能將歷史配息當作未來預測。
接入你的 Agent
- 外部 Agent 使用 GET 查詢;現有公開 GET 端點不需要登入憑證。POST 適用 LUVAI 網站的同源程式,仍受既有來源驗證保護。
- 先選需要的資料類別,並指定小筆數;例如只查個股時使用
types=stocks。 - 回答時保留結果的來源連結與日期,檢查是否為你要的股票或事件;未找到資料時回報缺少,不補造數字。
GET 範例
curl --get "https://stock.luvai.net/api/v1/kb/query" --data-urlencode "q=2330" --data-urlencode "types=stocks" --data-urlencode "limit=5"POST JSON 範例
以下為 POST 的 JSON 請求內容,適用 LUVAI 同源程式。外部 Agent 使用 GET;跨來源 POST 會受到來源驗證限制。
{"q":"2330","limit":5,"types":["stocks"]}查詢參數與回傳
- q
- 文字,最多 200 字。個股、主題、事件比對完整輸入;新聞以空白分詞,搜尋前 8 個詞中任一符合項目。標點會作為文字處理,不能用來執行搜尋運算子。空白查詢回傳空結果。
- limit
- 整數,預設 10,每類最多 20 筆;超出範圍的整數會限制到 1–20。
- types
- stocks、topics、events、news,預設全部。GET 使用逗號分隔,POST 使用字串陣列;可只取需要的類別。
結果位於 results 的四個類別;meta.total_matches 是本次回傳筆數,meta.query_ms 是查詢耗時。回傳筆數不等於全庫命中總數。
部分類別可用時仍回傳 200,保留成功類別,並以 meta.partial: true 與 meta.category_errors 標示未載入類別。失敗類別的空陣列不是查無結果,也不提供來源與查詢時間。query_paused 另有 retry_after_seconds;請等待指定秒數,不要連續重送。
meta.data_source 依類別標示來源:query 表示查詢結果或其快取;stock-catalog 表示既有個股基本資料快照,僅適用 stocks。來源標記不代表資料為最新行情。
meta.data_queried_at 保留各類原有 ISO 時間。來源是 query 時,這是上次成功查詢時間;來源是 stock-catalog 時,這是快照擷取時間。舊版回應若沒有來源標記,不推定其類型。這些時間不是新聞發布時間、事件日期或最新行情;未選取類別沒有來源與時間,請保留各筆資料原有日期。
新聞只提供日期時,試查只顯示發布日期,不補出時間;有效發布時間才換算成台灣時間。回傳資料無法完整保留為 JSON 時,試查會提示格式問題,不提供可複製的結果。
- 個股:用
code開啟/stock/<code>。 - 主題:用 URL 編碼後的
slug開啟/topics/<slug>。 - 事件/新聞:用
id開啟/events/<id>或/news/<id>,並保留事件/發布日期與來源。
沒有結果或查詢失敗時
- 200、空結果:先檢查
meta.category_errors,只將沒有失敗標記的類別視為查無結果;可縮短關鍵字或換成代號。 - 400:修正 JSON 或參數;
error_code與field可指出問題。 - 403、invalid_origin:POST 未通過來源驗證;外部 Agent 請使用 GET。
- 429:依
Retry-After等待再試;目前每 IP 每分鐘最多 30 次。 - 503、query_paused:本次選取的類別全部暫停且沒有可用資料。依
Retry-After等待,不要連續重送。若部分類別可用,則回傳 200 並標記未載入項目。上方試查收到整批或部分查詢的有效等待期限後,會暫停送出,修改條件也不會提前解除;到期後須自行按下試查,不會自動重送。 - 500:資料查詢暫時無法完成,稍後再試;服務不會改跑新聞全文模糊掃描。
查詢的是 GUYI 已收錄資料,可能延遲或不完整。輸入前請確認沒有個人敏感資訊;資料僅供研究與教學參考,不構成投資建議。
