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)	INLINECODE2	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

CODEBLOCK0

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

Quick Start

All scripts use uv run for dependency management.

Schedule

CODEBLOCK1

Standings

CODEBLOCK2

Game Results

CODEBLOCK3

Player Stats

CODEBLOCK4

League Leaders（排行榜）

CODEBLOCK5

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

Player Comparison（球員比較）

CODEBLOCK6

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（即時比分）✨

CODEBLOCK7

• - 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（單場詳情）✨

CODEBLOCK8

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

Notifications（比賽提醒）✨

CODEBLOCK9

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

Transactions（球員異動 / 交易）✨

CODEBLOCK10

• - 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	INLINECODE30, INLINECODE31	INLINECODE32, tpbl, or INLINECODE34
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
INLINECODE89	P. LEAGUE+ (4 teams)
INLINECODE90

台灣職業籃球大聯盟 (7 teams) |

Team Aliases

PLG

Alias	Full Name
富邦, 勇士	臺北富邦勇士
璞園, 領航猿

桃園璞園領航猿 |

| 台鋼, 獵鷹 | 台鋼獵鷹 | | 洋基, 洋基工程 | 洋基工程 | | 國王 | 新北國王 (已轉至 TPBL) | | 攻城獅 | 新竹街口攻城獅 (已轉至 TPBL) | | 夢想家 | 福爾摩沙台新夢想家 (已轉至 TPBL) | | 鋼鐵人 | 高雄鋼鐵人 (已解散) |

TPBL

Alias	Full Name
台新, 戰神	臺北台新戰神
中信, 特攻

新北中信特攻 |

| 國王 | 新北國王 | | 雲豹 | 桃園台啤永豐雲豹 | | 夢想家 | 福爾摩沙夢想家 | | 攻城獅 | 新竹御嵿攻城獅 | | 海神 | 高雄全家海神 |

Dependencies

Auto-installed via uv:

• - beautifulsoup4 — HTML parsing
• INLINECODE93 — Fast parser
• INLINECODE94 — 內建 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.
• INLINECODE106 output is unified to MM:SS format for both leagues.