xctf-data

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

XC/TF 数据工具（TFRRS — NCAA越野跑与田径项目）

Before writing queries, consult

references/api-reference.md

for parameters, URL conventions, and return shapes.

在编写查询前，请查阅

references/api-reference.md

了解参数、URL规则及返回数据格式。

Setup

安装配置

Before first use, check if the CLI is available:

bash

which sports-skills || pip install sports-skills

pip install

fails, install from GitHub:

bash

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.

首次使用前，检查CLI是否可用：

bash

which sports-skills || pip install sports-skills

如果

pip install

失败，从GitHub安装：

bash

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

要求Python 3.10及以上版本。无需API密钥，所有数据均来自TFRRS公开页面和The Stride Report的RSS订阅源。

Quick Start

快速开始

CLI (preferred):

bash

sports-skills xctf get_athlete_profile --athlete_id=8579610 --school=California_Baptist --name=Lamiae_Mamouni
sports-skills xctf get_news --limit=5

Python SDK:

python

from sports_skills import xctf

profile = xctf.get_athlete_profile(
    athlete_id="8579610",
    school="California_Baptist",
    name="Lamiae_Mamouni",
)

CLI（推荐方式）：

bash

sports-skills xctf get_athlete_profile --athlete_id=8579610 --school=California_Baptist --name=Lamiae_Mamouni
sports-skills xctf get_news --limit=5

Python SDK：

python

from sports_skills import xctf

profile = xctf.get_athlete_profile(
    athlete_id="8579610",
    school="California_Baptist",
    name="Lamiae_Mamouni",
)

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.
```
8579610
```
)
```
school
```
— school slug with underscores, not spaces (e.g.
```
California_Baptist
```
)
```
name
```
— athlete name slug (e.g.
```
Lamiae_Mamouni
```
)

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

以下三个参数为必填项，且必须与运动员的TFRRS URL完全匹配：

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

```
athlete_id
```
— 数字ID（例如
```
8579610
```
）
```
school
```
— 院校别名，使用下划线代替空格（例如
```
California_Baptist
```
）
```
name
```
— 运动员姓名别名（例如
```
Lamiae_Mamouni
```
）

请勿猜测别名，需访问tfrrs.org找到运动员页面后复制URL中的对应内容。

Commands

命令列表

Command	Description
`search_athlete`	Search the current team roster by name; returns `athlete_id` , `school` , and `name` slugs for use with `get_athlete_profile` . Searches both genders automatically. Current athletes only — graduated athletes require a direct TFRRS URL
`get_athlete_profile`	Athlete name, school, eligibility, all PRs, and full season-by-season meet results
`get_team_roster`	Full XC and/or TF roster for a team
`get_meet_results`	All event results and team scores from a TFRRS meet
`get_news`	Recent XC/TF articles from The Stride Report (thestridereport.com)

See

references/api-reference.md

for full parameter details and return shapes.

命令	描述
`search_athlete`	按姓名搜索当前队伍名单；返回 `athlete_id` 、 `school` 和 `name` 别名，用于 `get_athlete_profile` 命令。自动搜索男女运动员。仅支持现役运动员——已毕业运动员需要提供直接的TFRRS链接
`get_athlete_profile`	获取运动员姓名、院校、参赛资格、所有个人最佳成绩（PRs）以及完整的赛季赛事成绩历史
`get_team_roster`	获取队伍的完整XC和/或TF名单
`get_meet_results`	获取TFRRS赛事的所有项目成绩和队伍得分
`get_news`	获取The Stride Report（thestridereport.com）发布的最新XC/TF相关文章

如需了解完整参数详情及返回数据格式，请查阅

references/api-reference.md

。

Examples

使用示例

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

Call

search_athlete(name="Lamiae Mamouni", school="CA_college_f_California_Baptist")

Result:

data.matches

contains entries with

athlete_id

school

name

slugs

Call

get_athlete_profile(athlete_id="8579610", school="California_Baptist", name="Lamiae_Mamouni")

Result:

data.prs

contains all personal records by event (e.g.

{"1500": "4:31.80", "5K (XC)": "18:25.5", ...}

)

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

Call

search_athlete(name="Lamiae Mamouni", school="CA_college_f_California_Baptist")

Call
```
get_athlete_profile
```
with the matched athlete params
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:

Call

search_athlete(name="Katelyn Vuong", school="CA_college_f_UC_Davis")

Result:

data.matches

is empty — athlete has graduated

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."

User provides:

https://www.tfrrs.org/athletes/7899206/UC_Davis/Katelyn_Vuong.html

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:

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:

Find the meet on tfrrs.org and copy the meet_id and slug from the URL (e.g. tfrrs.org/results/95890/Stanford_Invitational)

Call

get_meet_results(meet_id="95890", slug="Stanford_Invitational")

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:

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

示例1：查询现役运动员的个人最佳成绩用户提问：“Lamiae Mamouni的个人最佳成绩有哪些？” 操作步骤：

调用

search_athlete(name="Lamiae Mamouni", school="CA_college_f_California_Baptist")

返回结果：

data.matches

包含带有

athlete_id

、

school

、

name

别名的条目

调用

get_athlete_profile(athlete_id="8579610", school="California_Baptist", name="Lamiae_Mamouni")

返回结果：

data.prs

包含各项目的个人最佳成绩（例如

{"1500": "4:31.80", "5K (XC)": "18:25.5", ...}

）

示例2：获取运动员的越野跑赛季成绩用户提问：“展示Lamiae Mamouni 2025年XC赛季的成绩” 操作步骤：

调用

search_athlete(name="Lamiae Mamouni", school="CA_college_f_California_Baptist")

使用匹配到的运动员参数调用
```
get_athlete_profile
```
从
```
data.meets
```
中筛选出日期在2025年秋季（2025年9-11月）的条目返回结果：包含赛事日期、项目、成绩和排名的列表

示例3：已毕业或转学运动员查询用户提问：“Katelyn Vuong在UC Davis时期的个人最佳成绩有哪些？” 操作步骤：

调用

search_athlete(name="Katelyn Vuong", school="CA_college_f_UC_Davis")

返回结果：

data.matches

为空——该运动员已毕业

告知用户：“Katelyn Vuong不在UC Davis当前的队伍名单中。请在tfrrs.org上找到她的档案链接（例如搜索'Katelyn Vuong UC Davis tfrrs'）并提供给我。”

用户提供链接：

https://www.tfrrs.org/athletes/7899206/UC_Davis/Katelyn_Vuong.html

从URL中提取参数并调用
```
get_athlete_profile(athlete_id="7899206", school="UC_Davis", name="Katelyn_Vuong")
```
注意：TFRRS会为XC和TF分别创建档案。如果两者都存在，请获取两个ID以获取完整的个人最佳成绩。

示例4：获取队伍当前名单用户提问：“展示UC Davis女子XC队伍的名单” 操作步骤：

调用
```
get_team_roster(school="CA_college_f_UC_Davis", sport="xc")
```
返回结果：包含运动员姓名、年级和档案别名的列表

示例5：获取赛事成绩用户提问：“展示Stanford Invitational的赛事成绩” 操作步骤：

在tfrrs.org上找到该赛事，从URL中复制
```
meet_id
```
和别名（例如 tfrrs.org/results/95890/Stanford_Invitational）
调用
```
get_meet_results(meet_id="95890", slug="Stanford_Invitational")
```
返回结果：该赛事的所有项目成绩和队伍得分

示例6：获取最新XC/TF新闻用户提问：“最新的大学田径新闻有哪些？” 操作步骤：

调用
```
get_news(limit=10)
```
返回结果：来自The Stride Report的近期文章列表，包含标题、日期、摘要和链接

Commands that DO NOT exist — never call these

不存在的命令——请勿调用

~~get_team_rankings~~
— does not exist. Use
```
get_athlete_profile
```
for individual data.
~~search_athletes~~
— does not exist. The correct command is
```
search_athlete
```
(no trailing 's').
~~fetch_news~~
— does not exist. The correct command is
```
get_news
```
.

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

~~get_team_rankings~~
— 不存在。如需个人数据，请使用
```
get_athlete_profile
```
。
~~search_athletes~~
— 不存在。正确命令为
```
search_athlete
```
（末尾无's'）。
~~fetch_news~~
— 不存在。正确命令为
```
get_news
```
。

如果命令未在上述命令列表中列出，则表示该命令不存在。

Error Handling

错误处理

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

For
```
get_athlete_profile
```
: confirm
```
athlete_id
```
,
```
school
```
, and
```
name
```
match the TFRRS URL exactly (case-sensitive)
For
```
search_athlete
```
: verify the team slug is correct by checking the team's TFRRS page URL
For
```
get_meet_results
```
: verify the
```
meet_id
```
and
```
slug
```
match the meet's TFRRS URL exactly
For
```
get_team_roster
```
: verify the school slug is correct
For
```
get_news
```
: if the feed fails, inform the user that The Stride Report may be temporarily unavailable
Report failure with a clean message only after exhausting alternatives

当命令执行失败时，请勿向用户显示原始错误信息。应按以下步骤处理：

对于
```
get_athlete_profile
```
：确认
```
athlete_id
```
、
```
school
```
和
```
name
```
与TFRRS URL完全匹配（区分大小写）
对于
```
search_athlete
```
：通过查看队伍的TFRRS页面URL验证队伍别名是否正确
对于
```
get_meet_results
```
：确认
```
meet_id
```
和别名与赛事的TFRRS URL完全匹配
对于
```
get_team_roster
```
：验证院校别名是否正确
对于
```
get_news
```
：如果订阅源加载失败，告知用户The Stride Report可能暂时无法访问
仅在尝试所有解决方法后，向用户显示简洁的失败提示信息

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

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.

get_meet_results
returns no events The

meet_id

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.

sports-skills
命令未找到运行

pip install sports-skills

或从GitHub安装（见上方安装配置部分）。

运动员档案返回HTTP 404错误

school

或

name

别名与TFRRS URL不完全匹配。别名区分大小写且使用下划线，请直接从tfrrs.org复制。

prs
返回空字典该运动员的档案页面可能非常新或结构不同，请直接访问tfrrs.org查看该URL。

search_athlete
返回空匹配结果该运动员可能已毕业或转学，请参考上方示例3处理。

get_meet_results
返回无项目数据

meet_id

或别名可能不正确，请直接从赛事的TFRRS URL复制两者。

get_news
执行失败或返回无文章 The Stride Report的RSS订阅源可能暂时无法访问，请稍后重试。

连接错误或超时 TFRRS可能暂时无法访问。请求会自动限制为每秒1次，请稍等片刻后重试。