🎁 Get the FREE AI Skills Starter GuideSubscribe →
BytesAgainBytesAgain
🦀 ClawHub

Taiwan Basketball

by @ichendong

Taiwan professional basketball stats, scores, schedules, player data, live scores, box scores, notifications, and transactions for PLG and TPBL.

Versionv1.3.5
Downloads536
TERMINAL
clawhub install taiwan-basketball

📖 About This Skill


name: taiwan-basketball description: "Taiwan professional basketball stats, scores, schedules for PLG and TPBL." tags: ["plg", "tpbl", "basketball", "taiwan", "sports", "scores", "standings"]

Taiwan Basketball Skill - 台灣職籃資訊查詢 🏀

Query PLG (P. LEAGUE+) and TPBL (台灣職業籃球大聯盟) game results, schedules, standings, player stats, league leaders, live scores, box scores, notifications, and transactions.

Data Sources

| Source | Description | |--------|-------------| | PLG official website | HTML scraping (server-side rendered) | | TPBL official REST API | api.tpbl.basketball | | Local SQLite DB | ~/.local/share/taiwan-basketball/basketball.db |

Features

| Feature | Script | Source | |---------|--------|--------| | Schedule (with countdown) | basketball_schedule.py | PLG website / TPBL API | | Standings | basketball_standings.py | PLG website / TPBL API | | Game results | basketball_games.py | PLG website / TPBL API | | Player stats | basketball_player.py | PLG website / TPBL API | | League leaders | basketball_leaders.py | PLG website / TPBL API | | Player comparison | basketball_compare.py | PLG website / TPBL API | | Live scores ✨ | basketball_live.py | TPBL API / PLG time-based | | Box Score ✨ | basketball_boxscore.py | TPBL API / PLG website | | Notifications ✨ | basketball_notify.py | PLG website / TPBL API | | Transactions ✨ | basketball_transactions.py | PLG news / TPBL API |

Architecture

scripts/
  _cache.py            # 磁碟 TTL 快取模組
  _http.py             # HTTP 工具(重試 / 快取)
  _utils.py            # 共用工具(格式化、球隊別名、並行擷取)
  _tpbl_api.py         # TPBL REST API 封裝
  _plg_api.py          # PLG HTML 爬蟲封裝
  _basketball_api.py   # 兼容性匯入層(維持所有腳本相容)
  _db.py               # SQLite 資料持久化模組
  basketball_*.py      # CLI 腳本

並行擷取:所有 --league all 查詢均使用 ThreadPoolExecutor 並行發送 PLG/TPBL 請求,大幅縮短等待時間。

Quick Start

All scripts use uv run for dependency management.

Schedule

uv run scripts/basketball_schedule.py --league plg
uv run scripts/basketball_schedule.py --league tpbl
uv run scripts/basketball_schedule.py --league all       # PLG + TPBL 合併查詢
uv run scripts/basketball_schedule.py -l plg --team 勇士
uv run scripts/basketball_schedule.py -l all --next      # 只顯示下一場比賽及倒數
uv run scripts/basketball_schedule.py -l all --format table

Standings

uv run scripts/basketball_standings.py --league plg
uv run scripts/basketball_standings.py --league tpbl
uv run scripts/basketball_standings.py --league plg --format table

Game Results

uv run scripts/basketball_games.py --league plg
uv run scripts/basketball_games.py --league tpbl
uv run scripts/basketball_games.py --league all            # PLG + TPBL 合併查詢
uv run scripts/basketball_games.py --league all --last 5   # 最近 5 場結果
uv run scripts/basketball_games.py -l tpbl --team 戰神
uv run scripts/basketball_games.py -l all --last 10 --format table

Player Stats

uv run scripts/basketball_player.py --league plg --player 林書豪
uv run scripts/basketball_player.py --league tpbl --player 林書豪
uv run scripts/basketball_player.py --league all --player 林書豪
uv run scripts/basketball_player.py -l plg -p 林書豪 --season 2023-24
uv run scripts/basketball_player.py -l tpbl -p 夢想家           # 球隊搜尋

League Leaders(排行榜)

uv run scripts/basketball_leaders.py --league plg --stat pts          # PLG 得分王
uv run scripts/basketball_leaders.py --league tpbl --stat reb --top 5 # TPBL 籃板前5名
uv run scripts/basketball_leaders.py -l tpbl -s ast --format table    # 表格輸出
uv run scripts/basketball_leaders.py -l all -s pts --top 10           # 雙聯盟得分榜

Supported --stat values: pts(得分)、reb(籃板)、ast(助攻)、stl(抄截)、blk(阻攻)、tov(失誤)、pf(犯規)、eff(效率值,TPBL 限定)

Player Comparison(球員比較)

uv run scripts/basketball_compare.py --league plg --player1 林書豪 --player2 戴維斯
uv run scripts/basketball_compare.py -l tpbl -p1 林志傑 -p2 陳盈駿
uv run scripts/basketball_compare.py -l plg -p1 林書豪 -p2 戴維斯 --season 2023-24
uv run scripts/basketball_compare.py -l plg -p1 林書豪 -p2 戴維斯 --format table

Supports fuzzy search by player name or team name. Returns per-season stats (GP, avg minutes/pts/reb/ast/stl/blk, FG/3P/FT splits, efficiency, PIR) plus career totals.

  • PLG: Scrapes /stat-player + /all-players for player index, then /player/{ID} for detailed per-season stats.
  • TPBL: Queries /games/stats/players?division_id={id} for all divisions across all seasons. Recalculates FG%/3P%/FT% from accumulated makes/attempts for cross-division accuracy.
  • Live Scores(即時比分)✨

    uv run scripts/basketball_live.py --league all
    uv run scripts/basketball_live.py --league tpbl --format table
    uv run scripts/basketball_live.py --league plg
    

  • TPBL: Returns games with status=IN_PROGRESS from official API.
  • PLG: Estimates live games based on scheduled time ±3 hours (no real-time API). Recommend visiting pleagueofficial.com for exact scores.
  • Box Score(單場詳情)✨

    # 先取得 game_id
    uv run scripts/basketball_games.py --league tpbl --last 5 --format table

    查詢 box score(TPBL 用數字 ID,PLG 用如 G101 格式)

    uv run scripts/basketball_boxscore.py --league tpbl --game-id 123 uv run scripts/basketball_boxscore.py --league plg --game-id G101 uv run scripts/basketball_boxscore.py --league tpbl --game-id 123 --format table

    Returns game summary (score, venue, date) and per-player stats (pts/reb/ast/stl/blk/tov/pf/min/FG splits/+/-).

    Notifications(比賽提醒)✨

    # 訂閱管理
    uv run scripts/basketball_notify.py add --team 戰神 --league tpbl
    uv run scripts/basketball_notify.py add --team 勇士 --league plg
    uv run scripts/basketball_notify.py list
    uv run scripts/basketball_notify.py remove --team 戰神 --league tpbl

    檢查提醒(訂閱的球隊,未來 24 小時)

    uv run scripts/basketball_notify.py check uv run scripts/basketball_notify.py check --hours 48 --format table

    臨時查詢(不需要先訂閱)

    uv run scripts/basketball_notify.py check --team 戰神 --league tpbl --hours 72

    Subscriptions are stored in the local SQLite database. Can be used with cron for automated alerts.

    Transactions(球員異動 / 交易)✨

    uv run scripts/basketball_transactions.py --league tpbl
    uv run scripts/basketball_transactions.py --league plg --format table
    uv run scripts/basketball_transactions.py --league all

    從本地 DB 讀取已儲存資料

    uv run scripts/basketball_transactions.py --league all --from-db

  • TPBL: Tries official API endpoints for transaction data.
  • PLG: Parses news page for player movement reports (transfers, signings, etc.).
  • Results are auto-saved to local SQLite DB for offline access.
  • CLI Parameters

    | Script | Param | Description | |--------|-------|-------------| | All | --league, -l | plg, tpbl, or all | | All | --format, -f | json (預設) or table (ASCII 表格) | | All | --no-cache | 停用磁碟快取 | | All | --debug | 輸出 debug 訊息(或設 BASKETBALL_DEBUG=1)| | schedule, games | --team, -t | Team name filter (supports aliases) | | basketball_schedule.py | --next | 只顯示下一場比賽及倒數計時 | | basketball_games.py | --last, -n | Show only last N results (default: all) | | basketball_player.py | --player, -p | Player name to search | | basketball_player.py | --season, -s | Filter by season (e.g., 2023-24) | | basketball_leaders.py | --stat, -s | Stat category (pts/reb/ast/stl/blk/tov/pf/eff) | | basketball_leaders.py | --top, -n | Show top N players (default: 10) | | basketball_compare.py | --player1, -p1 | First player name | | basketball_compare.py | --player2, -p2 | Second player name | | basketball_compare.py | --season, -s | Compare a specific season (default: career) | | basketball_boxscore.py | --game-id, -g | 比賽 ID(TPBL 數字,PLG 如 G101) | | basketball_notify.py check | --hours | 查詢未來幾小時內的比賽(預設 24) | | basketball_notify.py check | --team, -t | 指定球隊(不指定則用訂閱清單) | | basketball_transactions.py | --from-db | 從本地 DB 讀取(不發送 API 請求) | | basketball_transactions.py | --limit, -n | 最多顯示筆數(預設 30) |

    Output JSON includes a league field per game when using --league all.

    Caching

    Results are cached on disk at ~/.cache/taiwan-basketball/ with the following TTLs:

    | Data type | TTL | |-----------|-----| | Schedule | 5 minutes | | Game results | 10 minutes | | Standings | 10 minutes | | Player stats | 1 hour | | League leaders | 10 minutes | | Live scores | 1 minute | | Box Score | 5 minutes | | Transactions | 1 hour |

    Use --no-cache to bypass cache, or set BASKETBALL_DEBUG=1 to see cache hits/misses.

    League Codes

    | Code | League | |------|--------| | plg | P. LEAGUE+ (4 teams) | | tpbl | 台灣職業籃球大聯盟 (7 teams) |

    Team Aliases

    PLG

    | Alias | Full Name | |-------|-----------| | 富邦, 勇士 | 臺北富邦勇士 | | 璞園, 領航猿 | 桃園璞園領航猿 | | 台鋼, 獵鷹 | 台鋼獵鷹 | | 洋基, 洋基工程 | 洋基工程 | | 國王 | 新北國王 (已轉至 TPBL) | | 攻城獅 | 新竹街口攻城獅 (已轉至 TPBL) | | 夢想家 | 福爾摩沙台新夢想家 (已轉至 TPBL) | | 鋼鐵人 | 高雄鋼鐵人 (已解散) |

    TPBL

    | Alias | Full Name | |-------|-----------| | 台新, 戰神 | 臺北台新戰神 | | 中信, 特攻 | 新北中信特攻 | | 國王 | 新北國王 | | 雲豹 | 桃園台啤永豐雲豹 | | 夢想家 | 福爾摩沙夢想家 | | 攻城獅 | 新竹御嵿攻城獅 | | 海神 | 高雄全家海神 |

    Dependencies

    Auto-installed via uv:

  • beautifulsoup4 — HTML parsing
  • lxml — Fast parser
  • sqlite3 — 內建 Python 模組,無需安裝
  • Notes

  • PLG: Server-side rendered HTML, no JS needed. Standings page has full table.
  • TPBL: Official REST API at api.tpbl.basketball. Player stats via /games/stats/players?division_id={id} across all seasons.
  • Retry: All HTTP requests retry up to 3 times with exponential backoff on network errors.
  • FG% accuracy: TPBL percentage stats (FG%/3P%/FT%) are recalculated from cumulative makes/attempts for cross-division accuracy.
  • Season format: TPBL seasons display as YY/YY (e.g., 24/25); PLG seasons as YYYY-YY (e.g., 2023-24).
  • Live scores: TPBL API natively supports IN_PROGRESS status. PLG uses time-window estimation (±3h from scheduled time).
  • Box Score: TPBL tries multiple API endpoints; PLG scrapes individual game pages. If data is unavailable, a note field explains.
  • SQLite DB: Data is stored at ~/.local/share/taiwan-basketball/basketball.db. Schema is auto-created on first use.
  • Parallel fetch: --league all queries run PLG and TPBL requests concurrently using ThreadPoolExecutor.
  • SBL (超級籃球聯賽) is not supported — official site (sleague.tw) is a Vue SPA with authenticated GraphQL API.
  • avg_minutes output is unified to MM:SS format for both leagues.
  • 💡 Examples

    All scripts use uv run for dependency management.

    Schedule

    uv run scripts/basketball_schedule.py --league plg
    uv run scripts/basketball_schedule.py --league tpbl
    uv run scripts/basketball_schedule.py --league all       # PLG + TPBL 合併查詢
    uv run scripts/basketball_schedule.py -l plg --team 勇士
    uv run scripts/basketball_schedule.py -l all --next      # 只顯示下一場比賽及倒數
    uv run scripts/basketball_schedule.py -l all --format table
    

    Standings

    uv run scripts/basketball_standings.py --league plg
    uv run scripts/basketball_standings.py --league tpbl
    uv run scripts/basketball_standings.py --league plg --format table
    

    Game Results

    uv run scripts/basketball_games.py --league plg
    uv run scripts/basketball_games.py --league tpbl
    uv run scripts/basketball_games.py --league all            # PLG + TPBL 合併查詢
    uv run scripts/basketball_games.py --league all --last 5   # 最近 5 場結果
    uv run scripts/basketball_games.py -l tpbl --team 戰神
    uv run scripts/basketball_games.py -l all --last 10 --format table
    

    Player Stats

    uv run scripts/basketball_player.py --league plg --player 林書豪
    uv run scripts/basketball_player.py --league tpbl --player 林書豪
    uv run scripts/basketball_player.py --league all --player 林書豪
    uv run scripts/basketball_player.py -l plg -p 林書豪 --season 2023-24
    uv run scripts/basketball_player.py -l tpbl -p 夢想家           # 球隊搜尋
    

    League Leaders(排行榜)

    uv run scripts/basketball_leaders.py --league plg --stat pts          # PLG 得分王
    uv run scripts/basketball_leaders.py --league tpbl --stat reb --top 5 # TPBL 籃板前5名
    uv run scripts/basketball_leaders.py -l tpbl -s ast --format table    # 表格輸出
    uv run scripts/basketball_leaders.py -l all -s pts --top 10           # 雙聯盟得分榜
    

    Supported --stat values: pts(得分)、reb(籃板)、ast(助攻)、stl(抄截)、blk(阻攻)、tov(失誤)、pf(犯規)、eff(效率值,TPBL 限定)

    Player Comparison(球員比較)

    uv run scripts/basketball_compare.py --league plg --player1 林書豪 --player2 戴維斯
    uv run scripts/basketball_compare.py -l tpbl -p1 林志傑 -p2 陳盈駿
    uv run scripts/basketball_compare.py -l plg -p1 林書豪 -p2 戴維斯 --season 2023-24
    uv run scripts/basketball_compare.py -l plg -p1 林書豪 -p2 戴維斯 --format table
    

    Supports fuzzy search by player name or team name. Returns per-season stats (GP, avg minutes/pts/reb/ast/stl/blk, FG/3P/FT splits, efficiency, PIR) plus career totals.

  • PLG: Scrapes /stat-player + /all-players for player index, then /player/{ID} for detailed per-season stats.
  • TPBL: Queries /games/stats/players?division_id={id} for all divisions across all seasons. Recalculates FG%/3P%/FT% from accumulated makes/attempts for cross-division accuracy.
  • Live Scores(即時比分)✨

    uv run scripts/basketball_live.py --league all
    uv run scripts/basketball_live.py --league tpbl --format table
    uv run scripts/basketball_live.py --league plg
    

  • TPBL: Returns games with status=IN_PROGRESS from official API.
  • PLG: Estimates live games based on scheduled time ±3 hours (no real-time API). Recommend visiting pleagueofficial.com for exact scores.
  • Box Score(單場詳情)✨

    # 先取得 game_id
    uv run scripts/basketball_games.py --league tpbl --last 5 --format table

    查詢 box score(TPBL 用數字 ID,PLG 用如 G101 格式)

    uv run scripts/basketball_boxscore.py --league tpbl --game-id 123 uv run scripts/basketball_boxscore.py --league plg --game-id G101 uv run scripts/basketball_boxscore.py --league tpbl --game-id 123 --format table

    Returns game summary (score, venue, date) and per-player stats (pts/reb/ast/stl/blk/tov/pf/min/FG splits/+/-).

    Notifications(比賽提醒)✨

    # 訂閱管理
    uv run scripts/basketball_notify.py add --team 戰神 --league tpbl
    uv run scripts/basketball_notify.py add --team 勇士 --league plg
    uv run scripts/basketball_notify.py list
    uv run scripts/basketball_notify.py remove --team 戰神 --league tpbl

    檢查提醒(訂閱的球隊,未來 24 小時)

    uv run scripts/basketball_notify.py check uv run scripts/basketball_notify.py check --hours 48 --format table

    臨時查詢(不需要先訂閱)

    uv run scripts/basketball_notify.py check --team 戰神 --league tpbl --hours 72

    Subscriptions are stored in the local SQLite database. Can be used with cron for automated alerts.

    Transactions(球員異動 / 交易)✨

    uv run scripts/basketball_transactions.py --league tpbl
    uv run scripts/basketball_transactions.py --league plg --format table
    uv run scripts/basketball_transactions.py --league all

    從本地 DB 讀取已儲存資料

    uv run scripts/basketball_transactions.py --league all --from-db

  • TPBL: Tries official API endpoints for transaction data.
  • PLG: Parses news page for player movement reports (transfers, signings, etc.).
  • Results are auto-saved to local SQLite DB for offline access.
  • 📋 Tips & Best Practices

  • PLG: Server-side rendered HTML, no JS needed. Standings page has full table.
  • TPBL: Official REST API at api.tpbl.basketball. Player stats via /games/stats/players?division_id={id} across all seasons.
  • Retry: All HTTP requests retry up to 3 times with exponential backoff on network errors.
  • FG% accuracy: TPBL percentage stats (FG%/3P%/FT%) are recalculated from cumulative makes/attempts for cross-division accuracy.
  • Season format: TPBL seasons display as YY/YY (e.g., 24/25); PLG seasons as YYYY-YY (e.g., 2023-24).
  • Live scores: TPBL API natively supports IN_PROGRESS status. PLG uses time-window estimation (±3h from scheduled time).
  • Box Score: TPBL tries multiple API endpoints; PLG scrapes individual game pages. If data is unavailable, a note field explains.
  • SQLite DB: Data is stored at ~/.local/share/taiwan-basketball/basketball.db. Schema is auto-created on first use.
  • Parallel fetch: --league all queries run PLG and TPBL requests concurrently using ThreadPoolExecutor.
  • SBL (超級籃球聯賽) is not supported — official site (sleague.tw) is a Vue SPA with authenticated GraphQL API.
  • avg_minutes output is unified to MM:SS format for both leagues.