Baseball Savant OAA Integration

[grovecj]

Overview

Integrate with Baseball Savant to fetch Outs Above Average (OAA) data for the fielding component of gWAR.

Parent Issue

Part of #94 (WAR and Advanced Stats)

Data Source

Baseball Savant provides OAA leaderboard data via CSV export:

https://baseballsavant.mlb.com/leaderboard/outs_above_average?type=Fielder&year={year}&min=q&csv=true

CSV Fields

• player_id (MLB ID)
• player_name
• team
• outs_above_average (OAA)
• fielding_runs_prevented
• attempts

Files to Create

ingestion/client/BaseballSavantClient.java

@Component
public class BaseballSavantClient {
    private static final String OAA_LEADERBOARD_URL = 
        "https://baseballsavant.mlb.com/leaderboard/outs_above_average" +
        "?type=Fielder&year={year}&min=q&csv=true";
    
    public Map<Integer, Integer> getOaaByPlayerId(Integer season);
    private Map<Integer, Integer> parseCsvToOaaMap(String csv);
}

ingestion/service/OaaIngestionService.java

@Service
public class OaaIngestionService {
    public int syncOaaForSeason(Integer season);
}

common/config/RestClientConfig.java (modify)

Add Baseball Savant RestClient bean with appropriate timeout.

gWAR Fielding Calculation

// OAA to runs conversion
BigDecimal fieldingRuns = oaa != null 
    ? new BigDecimal(oaa).multiply(new BigDecimal("0.9"))
    : BigDecimal.ZERO;

The 0.9 multiplier converts outs saved to runs prevented (approximately 0.9 runs per out saved).

Sync Strategy

• Weekly sync (Sunday mornings) during season
• OAA data updates less frequently than box scores
• Store raw OAA value for transparency

Test Cases

• CSV parsing handles all edge cases
• Player ID mapping works correctly
• Missing players handled gracefully
• Rate limiting respected

Acceptance Criteria

• OAA data fetched from Baseball Savant
• CSV parsed and mapped to player IDs
• OAA stored on PlayerBattingStats entity
• gWAR fielding component uses OAA value
• Weekly sync job configured

Dependencies

• gWAR Schema: League Constants and Component Fields #169 (gWAR Schema) - OAA column exists
• gWAR Calculation Service #170 (gWAR Calculation Service) - Uses OAA for fielding

Notes

• Baseball Savant is an official MLB property
• No authentication required for CSV export
• Consider caching to reduce requests
• Players without OAA data get fielding = 0 (DH, pitchers)