API 文件

POST /api/analytics/arithmetic 分析模組

基本運算

示範用的最基本運算,驗證資料從前端送入、由分析引擎計算、再回傳的完整流程。

權限:免驗證(可附 API Key 以記錄用量)

輸入參數

欄位	型別	必填	說明
`a`	number	是	數字 A
`op`	string	是	運算:add / subtract / multiply / divide
`b`	number	是	數字 B(op=divide 時不可為 0)

請求範例

curl -X POST https://boshanweb.com/api/analytics/arithmetic \
  -H 'Content-Type: application/json' \
  -d '{"a":12.5,"op":"divide","b":4}'

成功回傳

{
    "ok": true,
    "id": "...",
    "type": "arithmetic",
    "result": {
        "operation": "divide",
        "a": 12.5,
        "b": 4,
        "result": 3.125
    },
    "duration_ms": 92
}

POST /api/analytics/statistics 分析模組

敘述統計

輸入一組數字,回傳平均數、變異數、標準差、最大最小值、偏態與峰態。

權限:免驗證(可附 API Key 以記錄用量)

輸入參數

欄位	型別	必填	說明
`data`	number[]	是	數值陣列,長度 3 至 100000

請求範例

curl -X POST https://boshanweb.com/api/analytics/statistics \
  -H 'Content-Type: application/json' \
  -d '{"data":[4,8,15,16,23,42]}'

成功回傳

{
    "ok": true,
    "id": "...",
    "type": "statistics",
    "result": {
        "mean": 18,
        "variance": 182,
        "stddev": 13.49074,
        "min": 4,
        "max": 42,
        "skewness": 1.24261,
        "kurtosis": 1.79975,
        "nobs": 6
    },
    "duration_ms": 88
}

POST /api/analytics/correlation 分析模組

線性迴歸(同步)

以最小平方法配適簡單線性迴歸,即時回傳截距、斜率與 R²。適合小量資料。

權限:免驗證(可附 API Key 以記錄用量)

輸入參數

欄位	型別	必填	說明
`x`	number[]	是	自變數數列
`y`	number[]	是	依變數數列(長度需與 x 相同)

請求範例

curl -X POST https://boshanweb.com/api/analytics/regression \
  -H 'Content-Type: application/json' \
  -d '{"x":[1,2,3,4,5],"y":[3,5,7,9,11]}'

成功回傳

{
    "ok": true,
    "id": "...",
    "type": "regression",
    "result": {
        "intercept": 1,
        "slope": 2,
        "rsquared": 1,
        "nobs": 5
    },
    "duration_ms": 83
}

POST /api/analytics/regression/async 背景任務

線性迴歸(背景)

把迴歸任務送入佇列,立即回傳查詢識別碼。適合大量資料或長時間運算,避免前端久等。

權限:免驗證(可附 API Key 以記錄用量)

輸入參數

欄位	型別	必填	說明
`x`	number[]	是	自變數數列
`y`	number[]	是	依變數數列

請求範例

curl -X POST https://boshanweb.com/api/analytics/regression/async \
  -H 'Content-Type: application/json' \
  -d '{"x":[1,2,3,4,5],"y":[3,5,7,9,11]}'

成功回傳

{
    "ok": true,
    "id": "uuid",
    "status": "queued",
    "status_url": "/api/analytics/runs/{uuid}"
}

POST /api/analytics/optivar 背景任務

OptiVaR 最適配置與風險值

第一組正式統計演算法(合作研究團隊提供)。輸入台股、那斯達克、原油三資產的每日收盤價,透過博山分析模組的計量引擎,以滾動估計與二次規劃求解最適投資組合權重(權重總和為 1;正值為做多部位、負值為放空部位,數值大於 1 則為融資部位);風險值(VaR)部分對非線性模型進行雙重收斂估計,配合前瞻式模擬方法,在給定信賴區間下預估未來特定交易日的最大可能損失。資料提供方式三選一:(1) dates/twn/nas/crude 四個 JSON 陣列;(2) data_file 直接上傳資料檔(multipart/form-data);(3) data_text 放資料檔的原始文字內容。三者都未提供時,自動使用內建範例資料(研究團隊提供的歷史日資料);參數未填則採用預設值。運算量大(預設參數約 1 分鐘),一律以背景任務執行,回傳查詢識別碼後以 GET /runs/{uuid} 輪詢結果。

權限:需要 API Key(後台「API 金鑰」頁建立,以請求標頭 X-API-Key 傳入);登入狀態下同源呼叫可免

輸入參數

欄位	型別	必填	說明
`dates`	int[]	否	日期陣列(yyyymmdd 數字),長度 3 至 100000;實際需 ≥ est + hold + 1。未提供資料時自動使用內建範例
`twn`	number[]	否	台股加權指數收盤價(長度需與 dates 相同;估計視窗內須為正數)
`nas`	number[]	否	那斯達克指數收盤價(長度需與 dates 相同;估計視窗內須為正數)
`crude`	number[]	否	原油價格(長度需與 dates 相同;估計視窗內須為正數)
`data_file`	file	否	改用檔案上傳時放這裡:multipart/form-data 的檔案欄位(.prn / .txt / .csv,上限 10MB)。每列四欄「日期台股收盤那斯達克收盤原油價格」,空白或逗號分隔;格式不符的列自動略過
`data_text`	string	否	同上格式的資料原始文字,直接放在 JSON 字串欄位(適合不方便用 multipart 的環境)
`est`	int	不可傳入	估計期間(滾動重估天數)。系統固定參數,由管理員於後台設定(目前 100);API 傳入會回 422
`hold`	int	不可傳入	權重估計視窗(回看天數)。系統固定參數,由管理員於後台設定(目前 500);API 傳入會回 422
`span`	int	否	預測天數,1 至 30,預設 3
`ndraws`	int	否	模擬次數,100 至 100000,預設 10000
`lower`	number	否	信賴下分位,0 至 0.5(不含),預設 0.025
`upper`	number	否	信賴上分位,0.5 至 1(不含),預設 0.975

請求範例

curl https://boshanweb.com/api/analytics/optivar \
  -H 'Accept: application/json'

成功回傳

{
    "ok": true,
    "id": "uuid",
    "status": "queued",
    "params": {
        "est": 100,
        "hold": 500,
        "span": 3,
        "ndraws": 10000,
        "lower": 0.025,
        "upper": 0.975
    },
    "status_url": "/api/analytics/runs/{uuid}"
}

GET /api/analytics/runs/{uuid} 背景任務

查詢任務結果

輪詢任務狀態。status 為 queued / running / success / failed,完成後 result 即為分析結果。OptiVaR 任務成功時 result 欄位為:weight_twn / weight_nas / weight_crude(三資產最適權重)、ew_return / mve_return(等權重與最適組合最近一日報酬 %)、var_lower / var_upper(未來 span 日累積報酬信賴區間 %)、as_of(計算依據的最後一筆資料日期)、summary(一段完整的中文操作參考結論)、nobs、params。

權限:免驗證(可附 API Key 以記錄用量)

輸入參數

欄位	型別	必填	說明
`uuid`	string	是	建立任務時回傳的識別碼(路徑參數)

請求範例

curl https://boshanweb.com/api/analytics/runs/{uuid} \
  -H 'Accept: application/json'

成功回傳

{
    "ok": true,
    "id": "uuid",
    "type": "regression",
    "status": "success",
    "result": {
        "intercept": 1,
        "slope": 2,
        "rsquared": 1,
        "nobs": 5
    },
    "duration_ms": 95
}

錯誤回傳格式

當輸入未通過驗證或運算發生錯誤時,API 會回傳對應的錯誤訊息。

驗證失敗(HTTP 422)

{
    "message": "The x.2 field must be a number.",
    "errors": {
        "x.2": [
            "The x.2 field must be a number."
        ]
    }
}

運算錯誤(HTTP 422)

{
    "ok": false,
    "id": "...",
    "error": "除數不可為 0"
}

基本運算

輸入參數

請求範例

成功回傳

敘述統計

輸入參數

請求範例

成功回傳

相關分析

輸入參數

請求範例

成功回傳

線性迴歸(同步)

輸入參數

請求範例

成功回傳

線性迴歸(背景)

輸入參數

請求範例

成功回傳

OptiVaR 最適配置與風險值

輸入參數

請求範例

成功回傳

查詢任務結果

輸入參數

請求範例

成功回傳

錯誤回傳格式

驗證失敗(HTTP 422)

運算錯誤(HTTP 422)

留下聯絡方式,專人與您聯繫