API 文件 — CPBL Analytics

總覽

端點

資源群組

GET

唯讀

該 API 使用 FastAPI 建置並透過 HTTPS 提供。所有回應均為 JSON。CORS 對瀏覽器客戶端開放。

互動式文件（Swagger UI）可在 /docs 取得。ReDoc 可在 /redoc 取得。

回應格式

大多數端點返回純 JSON 物件或陣列。/api/games 列出端點使用分頁信封：

分頁信封

{
  "items":    [ ... ],     // array of result objects
  "total":    370,          // total matching records
  "page":     1,             // current page (1-indexed)
  "per_page": 50             // items per page (max 200)
}

錯誤處理

該 API 使用標準 HTTP 狀態碼。錯誤回應遵循 FastAPI 的預設 JSON 格式：

404 找不到

{ "detail": "Game '20250401001' not found" }

422 驗證錯誤 — 無效的查詢參數

{
  "detail": [{ "loc": ["query", "year"], "msg": "value is not a valid integer", "type": "type_error.integer" }]
}

500 內部伺服器錯誤

{ "detail": "內部伺服器錯誤" }

Games

2 個端點

GET /api/games List games with optional filters, paginated

查詢參數

參數	類型	預設值	描述
year	integer	—	季節年份，例如 `2025`
team	string	—	按主隊或客隊代碼篩選，例如 `CTBC`
page	integer	1	頁碼（≥ 1）
per_page	integer	50	每頁項目數（1 – 200）

範例回應

{
  "items": [
    {
      "game_id":    "20250401001",
      "game_date":  "2025-04-01",
      "year":       2025,
      "home_team":  "CTBC",
      "away_team":  "UNI",
      "home_score": 5,
      "away_score": 3,
      "venue":      "天母棒球場",
      "kind_code":  "A",
      "source":     "rebas"
    }
  ],
  "total":    370,
  "page":     1,
  "per_page": 50
}

GET /api/games/{game_id} 按 ID 取得單一比賽

路徑參數

game_id — 字串，例如 20250401001。找不到時返回 404。

範例回應

{
  "game_id":    "20250401001",
  "game_date":  "2025-04-01",
  "year":       2025,
  "home_team":  "CTBC",
  "away_team":  "UNI",
  "home_score": 5,
  "away_score": 3,
  "venue":      "天母棒球場",
  "kind_code":  "A",
  "source":     "rebas"
}

Players

2 個端點

GET /api/players 列出所有球員，可選按球隊篩選

查詢參數

參數	類型	預設值	描述
team	string	—	按球隊代碼篩選，例如 `CTBC`、`UNI`、`RAKUTEN`

範例回應

[
  {
    "player_id": "P001234",
    "name_zh":  "林智勝",
    "name_en":  "Lin Chih-Sheng",
    "team":     "CTBC",
    "position": "1B",
    "bats":     "R",
    "throws":   "R"
  }
]

GET /api/players/{player_id} 按 ID 取得單一球員

路徑參數

player_id — 字串，例如 P001234。找不到時返回 404。

範例回應

{
  "player_id": "P001234",
  "name_zh":  "林智勝",
  "name_en":  "Lin Chih-Sheng",
  "team":     "CTBC",
  "position": "1B",
  "bats":     "R",
  "throws":   "R"
}

分析

9 個端點

從投球級別和逐球數據計算的進階分析。所有端點接受 year 參數（預設 2025）和閾值篩選器（min_ip 或 min_pa）以確保最小樣本量。

GET /api/analysis/lob LOB% 投手 LOB% 排行榜

留在壘百分比衡量投手滯留壘上跑者的頻率。聯盟平均約 70%。超過 78% 可能表示運氣；低於 65% 可能表示厄運。

查詢參數

參數	類型	預設值	描述
year	integer	2025	季節年份
min_ip	float	5.0	最少投球局數

範例回應

[
  {
    "player_id":   "P002345",
    "player_name": "王維中",
    "team":         "CTBC",
    "games":        18,
    "ip":           112.3,
    "lob_pct":     0.742,
    "league_avg":  0.701,
    "is_lucky":    false,
    "is_unlucky":  false,
    "sample_note": "sufficient sample"
  }
]

GET /api/analysis/lob/batters LOB% 打者 LOB（留在壘）費率

打者在有人在壘時上手時滯留跑者的頻率。高 lob_per_game 可能表示緊急狀況擊球差或不幸的序列。

查詢參數

參數	類型	預設值	描述
year	integer	2025	季節年份
min_pa	integer	10	最少打數（≥ 1）

範例回應

[
  {
    "player_id":       "P003456",
    "player_name":     "陳傑憲",
    "games":           87,
    "ab":              320,
    "h":               95,
    "rbi":             42,
    "lob":             67,
    "left_behind_lob": 31,
    "lob_per_game":   0.77
  }
]

GET /api/analysis/count-splits/{batter_id} 球數分組

打者表現按球數情況分解：前面（打者友善）、後面（投手友善）、平手和兩好球。包括每球分解和第一球揮棒率。

Path + 查詢參數

參數	位置	預設值	描述
batter_id	path	必填	球員 ID，例如 `P003456`
year	query	2025	季節年份

範例回應

{
  "player_id":   "P003456",
  "player_name": "陳傑憲",
  "role":        "batter",
  "total_pa":   345,
  "ahead": {
    "count": "ahead", "pa": 98, "ba": 0.312,
    "k_pct": 0.082, "bb_pct": 0.143
  },
  "behind": { "count": "behind", "pa": 112, "ba": 0.241, ... },
  "two_strike": { "count": "two_strike", "pa": 130, "ba": 0.198, ... },
  "first_pitch_swing_pct": 0.384,
  "by_count": [ /* array of CountStatsResponse per specific count */ ]
}

GET /api/analysis/pitcher-fatigue Fatigue 疲勞排行榜（所有投手）

所有合格投手的摘要統計：總投球數、疲勞閾值（表現下降時的投球數）和季度級別 BA 對戰 / K%。

查詢參數

參數	類型	預設值	描述
year	integer	2025	季節年份
min_ip	float	20.0	最少投球局數

範例回應

[
  {
    "pitcher_id":              "P002345",
    "team":                    "CTBC",
    "year":                    2025,
    "total_ip":               112.3,
    "games":                  18,
    "total_pitches":          1847,
    "fatigue_threshold_pitch": 85,
    "overall_ba_against":     0.253,
    "overall_k_pct":          0.224,
    "sample_note":            "sufficient sample"
  }
]

GET /api/analysis/pitcher-fatigue/{pitcher_id} Fatigue 單一投手的完整疲勞曲線

按 15 球分組的 BA 對戰、K% 和 BB% 分解。is_fatigue_point 標誌標記變點檢測到的降級分組。

Path + 查詢參數

參數	位置	預設值	描述
pitcher_id	path	必填	Player ID, e.g. `P002345`
year	query	2025	季節年份

範例回應

{
  "pitcher_id":              "P002345",
  "year":                    2025,
  "total_pitches":          1847,
  "games_analyzed":         18,
  "overall_ba_against":     0.253,
  "overall_k_pct":          0.224,
  "overall_bb_pct":         0.081,
  "fatigue_threshold_pitch": 85,
  "buckets": [
    {
      "bucket_index":   0,
      "pitch_start":   1,
      "pitch_end":     15,
      "batters_faced": 72,
      "ba_against":   0.222,
      "k_pct":        0.264,
      "is_fatigue_point": false
    },
    { "bucket_index": 5, "pitch_start": 76, "pitch_end": 90, "is_fatigue_point": true, ... }
  ],
  "sample_note": "sufficient sample"
}

GET /api/analysis/clutch 緊急狀況 / LI 緊急狀況擊球排行榜

按 clutch_score 排名打者：高槓桿局面（LI > 1.5）中的打擊率與整體打擊率之間的差異。正數 = 壓力下表現更好。

查詢參數

參數	類型	預設值	描述
year	integer	2025	季節年份
min_pa	integer	30	最少打數（≥ 1）

範例回應

[
  {
    "player_id":       "P003456",
    "player_name":     "陳傑憲",
    "total_pa":        345,
    "high_leverage_pa": 67,
    "high_li_ba":      0.328,
    "overall_ba":      0.297,
    "clutch_score":    0.031,
    "high_li_ops":     0.912,
    "sample_note":     "sufficient sample"
  }
]

GET /api/analysis/clutch/{batter_id} 緊急狀況 / LI 單一打者的緊急狀況統計

Path + 查詢參數

參數	位置	預設值	描述
batter_id	path	必填	球員 ID，例如 `P003456`
year	query	2025	季節年份

返回單一 LeverageResponse 物件（與排行榜項目相同的模式）。如果該球員/年份組合沒有槓桿數據，返回 404。