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 searchathlete(name="Jane Hedengren", school="UTcollegefBYU")

Result: data.matches contains entries with athlete_id, school, name slugs

1. Call getathleteprofile(athleteid="9230145", school="BYU", name="JaneHedengren")

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 searchathlete(name="Jane Hedengren", school="UTcollegefBYU")
2. Call getathleteprofile 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 searchathlete(name="Katelyn Vuong", school="CAcollegefUC_Davis")

Result: data.matches is empty — athlete has graduated

1. 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."
2. User provides: https://www.tfrrs.org/athletes/7899206/UCDavis/KatelynVuong.html
3. Extract params from the URL and call getathleteprofile(athleteid="7899206", school="UCDavis", 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 getteamroster(school="CAcollegefUCDavis", 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 meetid and slug from the URL (e.g. tfrrs.org/results/95890/StanfordInvitational)
2. Call getmeetresults(meetid="95890", slug="StanfordInvitational")

Result: All event results and team scores from the meet

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

Commands that DO NOT exist — never call these

• getteamrankings — does not exist. Use getathleteprofile for individual data.
• searchathletes — does not exist. The correct command is searchathlete (no trailing 's').
• fetchnews — does not exist. The correct command is getnews.

If a command is not listed in the Commands table above, it does not exist.

Error Handling

When a command fails, do not surface raw errors to the user. Instead:

1. For getathleteprofile: confirm athlete_id, school, and name match the TFRRS URL exactly (case-sensitive)
2. For search_athlete: verify the team slug is correct by checking the team's TFRRS page URL
3. For getmeetresults: verify the meet_id and slug match the meet's TFRRS URL exactly
4. For getteamroster: verify the school slug is correct
5. For get_news: if the feed fails, inform the user that The Stride Report may be temporarily unavailable
6. Report failure with a clean message only after exhausting alternatives

Troubleshooting

sports-skills command not found Run pip install sports-skills or install from GitHub (see Setup above).

HTTP 404 on athlete profile The school or name slug does not match the TFRRS URL exactly. Slugs are case-sensitive and use underscores. Copy directly from tfrrs.org.

prs returns empty dict The athlete's profile page may be very new or structured differently. Check the URL directly on tfrrs.org.

search_athlete returns empty matches The athlete is likely graduated or transferred. See Example 3 above for how to handle this.

getmeetresults returns no events The meet_id or slug may be incorrect. Copy both directly from the meet's TFRRS URL.

get_news fails or returns no articles The Stride Report RSS feed may be temporarily unavailable. Try again later.

Connection errors or timeouts TFRRS may be temporarily unavailable. Requests are throttled to 1 per second automatically — wait a moment and retry.