xctf-data

XC/TF データ（TFRRS — NCAA クロスカントリー＆陸上競技）

クエリを作成する前に、パラメーター、URL の規則、戻り値の形式について references/api-reference.md を確認してください。

セットアップ

初めて使用する前に、CLI が利用可能か確認してください。

which sports-skills || pip install sports-skills

pip install に失敗した場合は、GitHub からインストールしてください。

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

Python 3.10 以降が必要です。API キーは不要です。すべてのデータは TFRRS の公開ページと The Stride Report の RSS フィードから取得されます。

クイックスタート

CLI（推奨）：

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",
)

重要：クエリを実行する前に

次の 3 つのパラメーターはすべて必須で、選手の TFRRS URL と正確に一致している必要があります。

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

• athlete_id — 数値 ID（例：9230145）
• school — スペースではなく、アンダースコアを含む学校のスラッグ（例：BYU）
• name — 選手名のスラッグ（例：Jane_Hedengren）

スラッグを推測しないでください。tfrrs.org で選手のページに移動し、URL をコピーして確認してください。

コマンド

コマンド	説明
search_athlete	現在のチーム名簿を名前で検索します。get_athlete_profile で使用する athlete_id、school、name のスラッグを返します。男女両方を自動的に検索します。現役選手のみが対象です。卒業した選手については、TFRRS の URL を直接指定する必要があります
get_athlete_profile	選手名、学校、出場資格、すべての自己記録、およびシーズンごとの全大会結果を取得します
get_team_roster	チームの XC および／または TF の全選手名簿を取得します
get_meet_results	TFRRS の大会におけるすべての種目の結果とチームの得点を取得します
get_news	The Stride Report（thestridereport.com）の最近の XC/TF 記事を取得します

パラメーターと戻り値の形式の詳細については、references/api-reference.md を参照してください。

例

例 1：現役選手の自己記録を調べる ユーザー：「Jane Hedengren の自己記録は？」 操作：

1. search_athlete(name="Jane Hedengren", school="UT_college_f_BYU") を呼び出します 結果：data.matches に athlete_id、school、name のスラッグを含むエントリーが表示されます
2. get_athlete_profile(athlete_id="9230145", school="BYU", name="Jane_Hedengren") を呼び出します 結果：data.prs に種目ごとの自己記録が表示されます（例：{"1500": "4:10.24", "5000": "14:44.79", "6K (XC)": "18:29.6", ...}）

例 2：ランナーのクロスカントリーシーズンを調べる ユーザー：「Jane Hedengren の 2025 年 XC シーズンの結果を見せて」 操作：

1. search_athlete(name="Jane Hedengren", school="UT_college_f_BYU") を呼び出します
2. 一致した選手のパラメーターを指定して get_athlete_profile を呼び出します
3. data.meets の中から、date が 2025 年秋（2025 年 9 月～11 月）に該当するエントリーを絞り込みます 結果：日付、種目、記録、順位を含む大会の一覧

例 3：卒業または移籍した選手 ユーザー：「UC Davis 時代の Katelyn Vuong の自己記録は？」 操作：

1. search_athlete(name="Katelyn Vuong", school="CA_college_f_UC_Davis") を呼び出します 結果：選手は卒業しているため、data.matches は空です
2. ユーザーに次のように伝えます：「Katelyn Vuong は UC Davis の現在の選手名簿に掲載されていません。tfrrs.org でプロフィール URL を探して（例：'Katelyn Vuong UC Davis tfrrs' で検索）、共有してください。」
3. ユーザーが次の URL を提供します：https://www.tfrrs.org/athletes/7899206/UC_Davis/Katelyn_Vuong.html
4. URL からパラメーターを抽出し、get_athlete_profile(athlete_id="7899206", school="UC_Davis", name="Katelyn_Vuong") を呼び出します 注：TFRRS は XC と TF で別々のプロフィールを作成します。両方ある場合は、自己記録をすべて確認するため、両方の ID を取得してください。

例 4：チームの現在の選手名簿を取得する ユーザー：「UC Davis 女子 XC チームの選手名簿を見せて」 操作：

1. get_team_roster(school="CA_college_f_UC_Davis", sport="xc") を呼び出します 結果：名前、学年、プロフィールのスラッグを含む選手一覧

例 5：大会の結果を取得する ユーザー：「Stanford Invitational の結果を見せて」 操作：

1. tfrrs.org で大会を探し、URL から meet_id とスラッグをコピーします（例：tfrrs.org/results/95890/Stanford_Invitational）
2. get_meet_results(meet_id="95890", slug="Stanford_Invitational") を呼び出します 結果：大会のすべての種目の結果とチーム得点です。各結果には place、name、year、team、marks（記録されたタイムや距離。例：["9.72"] または ["DNF"]）、score（チームの得点。得点対象外の大会では null）が含まれます。種目に該当する場合は、wind、conversion（ヤード・ポンド法での記録）、リレーの athletes も表示されます。

クロスカントリー大会の場合（URL の例：tfrrs.org/results/xc/28714/Gans_Creek_Classic）、sport="xc" を渡します：get_meet_results(meet_id="28714", slug="Gans_Creek_Classic", sport="xc")。XC の team_scores はレース名をキーとして使用します。XC の ID は別の範囲を使用するため、sport="xc" を指定せずに XC の ID を渡すと、無関係なトラック大会が返されます（warnings にその旨が示されます）。

例 6：最新の XC／TF ニュースを取得する ユーザー：「大学の陸上競技に関する最新ニュースは？」 操作：

1. get_news(limit=10) を呼び出します 結果：The Stride Report の最近の記事が、タイトル、日付、要約、リンクとともに表示されます

存在しないコマンド — 絶対に呼び出さないでください

• get_team_rankings — 存在しません。個人のデータには get_athlete_profile を使用してください。
• search_athletes — 存在しません。正しいコマンドは search_athlete です（末尾に「s」は付きません）。
• fetch_news — 存在しません。正しいコマンドは get_news です。

上記の Commands テーブルに記載されていないコマンドは存在しません。

エラー処理

コマンドが失敗した場合、生のエラーをユーザーに表示しないでください。代わりに、次の手順を実行してください。

1. get_athlete_profile の場合：athlete_id、school、name が TFRRS の URL と完全に一致していることを確認します（大文字と小文字を区別します）
2. search_athlete の場合：チームの TFRRS ページ URL を確認して、チームのスラッグが正しいことを確かめます
3. get_meet_results の場合：meet_id と slug が大会の TFRRS URL と完全に一致していることを確認します
4. get_team_roster の場合：学校のスラッグが正しいことを確認します
5. get_news の場合：フィードの取得に失敗したら、The Stride Report が一時的に利用できない可能性があることをユーザーに伝えます
6. ほかの手段をすべて試した後に限り、わかりやすいメッセージで失敗を報告します

トラブルシューティング

sports-skills コマンドが見つからない pip install sports-skills を実行するか、GitHub からインストールしてください（上記のセットアップを参照）。

アスリートのプロフィールで HTTP 404 が発生する school または name のスラッグが TFRRS の URL と完全に一致していません。スラッグは大文字と小文字を区別し、アンダースコアを使用します。tfrrs.org から直接コピーしてください。

prs が空の dict を返す アスリートのプロフィールページが公開されたばかりか、構造が異なる可能性があります。tfrrs.org で URL を直接確認してください。

search_athlete が空の一致結果を返す アスリートは卒業済みか、転校した可能性があります。この場合の対処方法は、上記の例 3 を参照してください。

get_meet_results がイベントを返さない meet_id または slug が正しくない可能性があります。大会の TFRRS URL から両方を直接コピーしてください。URL に /results/xc/ が含まれている場合は、sport="xc" を渡してください。

get_news が失敗する、または記事を返さない The Stride Report の RSS フィードが一時的に利用できない可能性があります。しばらくしてから再試行してください。

接続エラーまたはタイムアウト TFRRS が一時的に利用できない可能性があります。リクエストは自動的に 1 秒あたり 1 件に制限されています。少し待ってから再試行してください。