Skip to content

README.md

Latest commit

 

History

History
149 lines (110 loc) · 3.77 KB

README.md

File metadata and controls

149 lines (110 loc) · 3.77 KB

FTCStats Python API

A Python client for accessing FTCStats EPA analytics data for FIRST Tech Challenge (FTC).

Installation

pip install ftcstats

Or install from source:

cd api
pip install -e .

Quick Start

import ftcstats

# Get team data
team = ftcstats.get_team(12345)
print(f"Team {team.number}: {team.name}")
print(f"Normalized EPA: {team.norm_epa.current}")

# Get top teams for a season
response = ftcstats.get_team_seasons(2024, limit=10)
for ts in response.team_seasons:
    print(f"{ts.team_number}: EPA {ts.epa.total:.1f}")

# Get event matches with predictions
matches = ftcstats.get_event_matches(2024, "USWATACO")
for match in matches:
    if match.pred.red_win_prob:
        prob = match.pred.red_win_prob
        winner = "Red" if prob > 0.5 else "Blue"
        print(f"{match.match_id}: {winner} favored ({max(prob, 1-prob):.0%})")

Using a Custom Client

For local development or custom configuration:

import ftcstats

# Create a custom client
client = ftcstats.FTCStats(base_url="http://localhost:8000/v1/site")

# Use client methods
team = client.get_team(12345)
teams = client.get_teams(country="USA", state="WA", limit=50)

# Or set as default for module-level functions
ftcstats.set_client(client)
team = ftcstats.get_team(12345)  # Uses custom client

API Reference

Team Functions

Function Description
get_team(team) Get team data with EPA statistics
get_teams(...) Get paginated list of teams with filters
get_team_seasons(season, limit, metric) Get season info and team performances
get_team_season(season, team) Get team performance for a specific season
get_team_season_events(season, team) Get team's events in a season
get_team_season_matches(season, team) Get team's matches in a season

Event Functions

Function Description
get_events(...) Get paginated list of events with filters
get_event(season, code) Get event data
get_event_teams(season, code) Get teams at an event
get_event_matches(season, code) Get matches at an event

Match Functions

Function Description
get_match(season, event, match_id) Get match data with predictions
get_matches(...) Get matches with filters

Season Functions

Function Description
get_seasons() Get all seasons
get_season(season) Get season statistics

Data Models

All responses are returned as Pydantic models with full type hints:

from ftcstats import Team, TeamSeason, Event, Match

team: Team = ftcstats.get_team(12345)
team.number      # int
team.name        # Optional[str]
team.norm_epa    # NormEPA with .current, .recent, .mean, .max
team.record      # TeamRecords with .season and .full

ts: TeamSeason = ftcstats.get_team_season(2024, 12345)
ts.epa.total     # float - Total EPA
ts.epa.auto      # float - Auto EPA
ts.epa.dc        # float - Driver-controlled EPA  
ts.epa.endgame   # float - Endgame EPA
ts.epa.norm      # float - Normalized EPA (1500 scale)
ts.epa.ranks     # EPARanks with .total, .country, .state, .region

match: Match = ftcstats.get_match(2024, "USWATACO", "Q1")
match.pred.winner        # Predicted winner
match.pred.red_win_prob  # Red alliance win probability
match.pred.red_score     # Predicted red score
match.result             # MatchResult (if played)

Error Handling

The client raises httpx.HTTPStatusError for API errors:

import httpx

try:
    team = ftcstats.get_team(99999999)
except httpx.HTTPStatusError as e:
    if e.response.status_code == 404:
        print("Team not found")
    else:
        raise

Requirements

  • Python 3.9+
  • httpx
  • pydantic

License

MIT