Xctf Data

XC/TF Data (TFRRS — NCAA Cross Country & Track and Field)

Before writing queries, consult references/api-reference.md for parameters, URL conventions, and return shapes.

Setup

Before first use, check if the CLI is available:

which sports-skills || pip install sports-skills

If pip install fails, install from GitHub:

pip install git+https://github.com/machina-sports/sports-skills.git

Requires Python 3.10+. No API keys required. All data comes from TFRRS public pages and The Stride Report RSS feed.

Quick Start

CLI (preferred):

sports-skills xctf get_athlete_profile --athlete_id=9230145 --school=BYU --name=Jane_Hedengren
sports-skills xctf get_news --limit=5

Python SDK:

from sports_skills import xctf

profile = xctf.get_athlete_profile(
    athlete_id="9230145",
    school="BYU",
    name="Jane_Hedengren",
)

CRITICAL: Before Any Query

All three parameters are required and must match the athlete's TFRRS URL exactly:

https://www.tfrrs.org/athletes/{athlete_id}/{school}/{name}.html

• athlete_id — numeric ID (e.g. 9230145)
• school — school slug with underscores, not spaces (e.g. BYU)
• name — athlete name slug (e.g. Jane_Hedengren)

Do NOT guess slugs. Find them by navigating to the athlete on tfrrs.org and copying the URL.

Commands

See references/api-reference.md for full parameter details and return shapes.

Examples

Example 1: Look up a current athlete's PRs User says: "What are Jane Hedengren's PRs?" Actions:

1. Call search_athlete(name="Jane Hedengren", school="UT_college_f_BYU") Result: data.matches contains entries with athlete_id, school, name slugs
2. Call get_athlete_profile(athlete_id="9230145", school="BYU", name="Jane_Hedengren") Result: data.prs contains all personal records by event (e.g. {"1500": "4:10.24", "5000": "14:44.79", "6K (XC)": "18:29.6", ...})

Example 2: Get a runner's cross country season User says: "Show me Jane Hedengren's 2025 XC season results" Actions:

1. Call search_athlete(name="Jane Hedengren", school="UT_college_f_BYU")
2. Call get_athlete_profile with the matched athlete params
3. Filter data.meets for entries whose date falls in the fall of 2025 (Sep–Nov 2025) Result: List of meets with dates, events, marks, and places

Example 3: Graduated or transferred athlete User says: "What are Katelyn Vuong's PRs from UC Davis?" Actions:

1. Call search_athlete(name="Katelyn Vuong", school="CA_college_f_UC_Davis") Result: data.matches is empty — athlete has graduated
2. Tell the user: "Katelyn Vuong is not on UC Davis's current roster. Please find her profile URL on tfrrs.org (e.g. search 'Katelyn Vuong UC Davis tfrrs') and share it."
3. User provides: https://www.tfrrs.org/athletes/7899206/UC_Davis/Katelyn_Vuong.html
4. Extract params from the URL and call get_athlete_profile(athlete_id="7899206", school="UC_Davis", name="Katelyn_Vuong") Note: TFRRS creates separate profiles for XC and TF. If both exist, fetch both IDs for complete PRs.

Example 4: Get a team's current roster User says: "Show me the UC Davis women's XC roster" Actions:

1. Call get_team_roster(school="CA_college_f_UC_Davis", sport="xc") Result: List of athletes with name, year, and profile slugs

Example 5: Get results from a meet User says: "Show me the results from the Stanford Invitational" Actions:

1. Find the meet on tfrrs.org and copy the meet_id and slug from the URL (e.g. tfrrs.org/results/95890/Stanford_Invitational)
2. Call get_meet_results(meet_id="95890", slug="Stanford_Invitational") Result: All event results and team scores from the meet. Each result has place, name, year, team, marks (the recorded mark, e.g. ["9.72"], or ["DNF"]) and score (team points, null at unscored meets); wind, conversion (imperial mark) and relay athletes appear when the event has them.

For a cross-country meet (URL like tfrrs.org/results/xc/28714/Gans_Creek_Classic) pass sport="xc": get_meet_results(meet_id="28714", slug="Gans_Creek_Classic", sport="xc"). XC team_scores are keyed by race name. XC ids use a separate range, so an XC id without sport="xc" returns an unrelated track meet (flagged in warnings).

Example 6: Get the latest XC/TF news User says: "What's the latest college track news?" Actions:

1. Call get_news(limit=10) Result: Recent articles from The Stride Report with title, date, summary, and link