Baseball Savant教學：球種篩選與逐球匯出

Baseball Savant查詢逐球數據，先固定Season、Season Type與Pitch Type，再從結果工具列選Download Individual Pitch Data下載逐球CSV。 Group By顯示的球員彙總表，和一列一球的資料用途不同；要讓別人重查，還要留下完整網址、擷取日與原始檔。

這份Baseball Savant教學依2026年10月25日官方介面實測，以2024年4月1日MLB例行賽的四縫線速球為例。重點是把查詢做對、保存得完整；AB、OPS等基礎縮寫另見〈棒球術語與數據解釋〉。

一、先寫查詢問題，再開篩選器

打開官方Statcast Search，先寫下：「我要哪些比賽、哪一種球、每列代表什麼？」本次問題是取得指定日期的四縫線速球紀錄，不是找單日投手排行榜，也不是估計下場比賽。

本次不限制球員、球隊、左右手、投球結果或打席結果。若一開始同時選球種、好球帶、揮空及兩好球，得到的只是多個條件交集，不能再稱為「該球種全部投球」。

二、球季、日期與球種怎麼選？

以下按實際操作順序設定。網頁可能更新預設年份，別直接沿用開頁時的值。

1. 展開Season，取消原先勾選的年份，只勾2024。這是可複選欄位，多留一年就會改變查詢範圍。
2. 確認Season Type為Regular Season。若研究季後賽，另選對應類型，別把兩者混稱同一份例行賽資料。
3. 在Game Date >=與Game Date <=都輸入2024-04-01。使用網站的比賽日期，不自行換成台灣觀看比賽的日期。
4. 展開Pitch Type，勾選Four Seamer，收合後本次顯示為4-Seam。不要直接勾Fastball整組，因為選單還包含Sinker、Cutter等項目。
5. Player Type保留Pitcher，Group By選Player；PA Result、Pitch Result及其他額外條件留空，按Search。

Player Type選Pitcher，不等於選好某一名投手。若只查一人，還要在Pitchers輸入姓名並選取候選項；查打者則使用Batters。Team和Opponent也分開列出，新增條件後務必重看輸出是否符合你的問題。

初次測試先用一天，確認成功後再擴大日期。若頁面遲遲沒完成，先縮短期間，或依官方提示重新整理重試，不要把未載完的空畫面當成零筆紀錄。

三、彙總表與逐球CSV是兩種輸出

本次Group By選Player，結果先按球員列出Pitches、Total、Pitch %。點球員姓名可展開逐球明細，看到日期、球種、球速、轉速、球數、局數、投球結果與打席結果。

Total不一定是你以為的分母

本次實測第一列的Pitches為63、Total為1,708，Pitch %顯示3.7；63 ÷ 1,708 × 100 ≈ 3.7%。這個百分比不能直接解讀成「該投手當天有3.7%的球是四縫線速球」，因為Total沒有與本次單日篩選形成相同範圍的全部投球分母。

頁面另有Change Total Pitch Parameters，涉及Total的條件設定。要算某天的球種使用率，較容易核對的方式是：保持同一投手、日期及賽事類型，另查未限制Pitch Type的逐球資料，再以四縫線球數除以同範圍全部球數。不能只把現成百分比抄進報告。

下載時確認工具名稱

結果區右上工具列有兩種下載入口，圖示載入不完整時可把滑鼠移到圖示上辨認名稱。

• Download Aggregated Results：下載彙總結果，適合保留目前分組表。
• Download Individual Pitch Data：下載個別投球資料，是本篇要的逐球CSV。

本次使用結果區的Download Individual Pitch Data，實際取得1,417列資料、119個欄位，不含表頭列；game_date全部為2024-04-01，pitch_type全部為FF。這是本次擷取的核對結果，不保證官方日後修訂資料後筆數永遠不變。

四、逐球示例：空白不等於零

以下從本次CSV取同一打席的3球，依投球先後重新排列，移除球員姓名、球員ID及比賽ID，以甲、乙、丙作教學列號。數值來自實測下載檔，沒有改成虛構數字；這是省略識別欄位的教學節錄，不宣稱不可回查到原始比賽。

三球的pitch_type都是FF；球速欄為release_speed，擊球初速欄為launch_speed，單位皆為mph。

甲是看著好球進壘，沒有擊球初速可填；乙是界外球，也可能有擊球追蹤值；丙是擊進場內。不能用「擊球初速有值」直接代替「形成場內擊球結果」的判定。

這3列的events依序為空白、空白、field_out。description描述該球結果，events記錄打席結果；前兩球的events空白，不代表那兩列無效，更不能先刪掉再說自己保留了全部投球。

算平均時，先說清楚哪些列有資格進分母

三球平均球速為（94.1＋94.5＋95.5）÷ 3＝94.7 mph。若只是示範「兩筆有值的擊球初速平均」，則是（88.1＋97.3）÷ 2＝92.7 mph；它包含一顆界外球，不能冒充官方場內擊球平均指標。把甲填0再除以3，會錯算成61.8 mph。

整份1,417列的本次檔案中，球速與轉速欄沒有空白，擊球初速、擊球仰角各有905列空白，events有1,068列空白。這些是欄位空白數，不是905次追蹤失敗或1,068筆錯誤；是否適用該欄位，須連同投球與打席結果判讀。

五、保存條件、欄位與清理紀錄，才能重查

只留一張排行榜截圖不夠。建議每次保存下列資料，檔名使用明確日期與球種，例如2024-04-01-FF-raw.csv；整理版另存，不覆蓋原始檔。

1. 完整搜尋網址與條件清單：球季、賽事、日期、球種、球員、分組，以及哪些欄位留空。按Search後再複製網址，並重新開啟核對。
2. 擷取日期與原始CSV：本文為2026年10月25日；記下1,417列、119欄，讓下一次能辨認資料是否改變。
3. 操作截圖：至少保留篩選器與逐球明細兩個畫面，協助核對當時設定，但截圖不取代原檔。
4. 清理說明：是否排序、刪除重複列、排除哪些結果、缺值如何處理，以及每個平均值使用的有效筆數。

本次CSV帶有UTF-8 BOM。用Python讀取時採encoding='utf-8-sig'，可避免第一個欄名混入BOM字元；用試算表匯入時選UTF-8，確認表頭是pitch_type，不要直接假定第一欄名稱一定已乾淨。

欄位名以實際表頭為準，定義再對照官方文件

官方CSV文件可查每欄用途。本次下載的轉速欄實際叫release_spin_rate，球速是release_speed；不要因文件章節名稱或舊教材不同，就憑位置把兩欄讀錯。標有deprecated的舊欄位也不應和現行欄位混用。

要檢查逐球重複，可先保留game_pk、at_bat_number、pitch_number作為比賽、打席、打席內球序的組合，再檢查是否重複；本篇示例才省略識別值。資料若已限定單一球種，球序中間跳號可能只是其他球種被篩掉，不要自行補球。

官方文件另註明：plate_x、plate_z到2025年採本壘板前緣，2026年起改為中間位置；sz_top、sz_bot在2026年起採ABS定義的好球帶上下緣。跨年度研究位置時，應註記這個定義改變，不能只因欄名相同便視為完全相同量測。

官方搜尋頁也說明球速資料在2008～2016年使用Pitch F/X並作出手點調整，2017年起使用Statcast出手球速。這些版本差異要隨原檔記錄，不能把2026年擷取日誤寫成所有資料都由2026年設備量測。

六、常見問題

為什麼CSV列數和打席數不同？

逐球檔以投球紀錄為單位，一個打席通常含多球。球種篩選還會讓打席只留下部分球，不能把1,417列稱為1,417個完整打席。

查不到某名球員，是不是當天沒投那種球？

先確認姓名已從候選清單選入，球季與日期相容，且沒有殘留PA Result、左右手或最低筆數門檻。只有查詢完成、條件核對無誤後，才能描述為「這組條件沒有回傳資料」。

為什麼畫面有擊球數值，卻不能直接當成場內擊球？

本次實測的界外球也出現擊球初速與仰角。計算前要定義研究的事件集合，再核對description與events，不能只篩「非空白」。

保存網址後，每次重查都會得到相同結果嗎？

網址保存條件，不能凍結官方資料。保留原始CSV、擷取日期、筆數與欄位清單，才有辦法說明新舊結果的差異；本篇未宣稱官方提供固定版號或永久不變的下載檔。

七、重點整理：先核對範圍，再解讀數字

完成一次可核對的Statcast查詢，要能回答三件事：選了哪些球、每列是什麼、缺值與分母怎麼處理。先用單日四縫線範例熟悉流程，再擴大到球員或整季，會比一開始堆滿篩選條件更容易查錯。

若接著要比較左右投、主客場或不同期間，延伸閱讀〈棒球分項成績與小樣本比較〉。數據用來幫助理解已發生的比賽；若參與賽事娛樂，仍應設定時間與預算，不把歷史數字當成下一場結果的保證。