あなたはアーセナルのニューカッスルへのアウェイゲームに合わせて土曜日の予定を立てています。ニューヨークの友人がキックオフ時刻を知りたがっています。するとグループチャットの誰かが、アーセナルの前回のアウェイ戦の結果を尋ねてきました。最初の答えは試合日程のリストを見ればわかります。2つ目の答えのためには、「リバプール 0-1 アーセナル」というスコアの1点がどちらのチームのものかを知る必要があります。
プレミアリーグの次の3試合の日程、アーセナルの直近リーグ5試合の結果、そして順位表での位置を調べられるサッカーチャットボット、Matchday Notebookを作成します。このサンプルは2026年11月18日時点のデータに固定されています。ニューカッスルでのアウェイ戦は11月21日土曜日17:30(UTC)、ニューヨーク時間では午後12:30に予定されていました。
プロバイダーの試合ページとプライベートのAgentで、キックオフ時刻が一致しています。このQuickchat AIでの会話は、過去の公開記録のリプレイデータに対して実行されたもので、以下で再現できます。
ニューカッスル戦の試合日程を確認するか、Matchday Notebookキットをダウンロードしてください。zipファイルを解凍してpython3 replay.pyを実行すると、アカウントなしで3試合の日程、5試合の結果、順位表の行が表示されます。同じキットには、アクション設定と独自のフィードを接続するためのMain Promptが含まれています。
1. チャットボットでどのクラブと大会を追いますか?
最初にクラブとリーグを指定します。火曜夜に行われる欧州の大会まで含めると、アーセナルの直近の成績はリーグ戦だけを数えた場合と変わります。このノートでは、チームID 57 がアーセナル、大会ID 2021 がプレミアリーグです。リーグコードは PL です。
- football-data.orgの登録フォームを開きます。名前とメールアドレスを入力し、利用規約に同意してCreate accountを選択します。対応リーグ一覧でご希望の大会が対象か確認してください。無料プランにはプレミアリーグが含まれており、試合日程とスコアが遅れて配信されます。
確認できるメールアドレスを使用してください。登録後、football-data.orgからAPIキーがそのアドレスに送信されます。無料プランでは、1分当たりのリクエスト上限は10回です。
アカウントを既にお持ちの場合は、メールアドレスとAPIトークンでサインインしてください。トークンの再送が必要な場合は、登録したアドレスを使ってメールでリクエストします。このトークンはステップ2の保護されたヘッダーで使いますので、保管しておいてください。
「Subscription」でご自身のプランを確認し、「Available competitions」で対象リーグを探します。この抜粋には、UEFAチャンピオンズリーグ(CL)とブンデスリーガ(BL1)が表示されています。
- 別のクラブを追うには、大会のチームリスト(たとえば
GET /v4/competitions/PL/teams)で検索します。返されたチームIDと大会IDを、後述の試合リクエストで使用します。v4クイックスタートに両方の検索方法が記載されています。 - Quickchat AIエージェントを作成し、Matchday Notebookと名付け、テスト中は非公開にしてください。会話とシミュレーションには利用可能なクレジットが必要です。Identity → AI Persona → Main Promptを開き、以下の指示を貼り付けます。スクリーンショットとコピー可能な設定は英語を使用しています。
両方の場所で同じクラブ情報を維持してください。製品内では、Agentの指示はIdentityにあります。
Matchday Notebook Main Promptをコピーする
You are Matchday Notebook, an Arsenal Premier League companion. Use get_club_fixtures for the schedule, get_recent_results for form and get_league_standings for the league table. For match reads, use an inclusive UTC start date and an exclusive end date. Ask for dates when the window is unclear.
List up to the requested number of TIMED or SCHEDULED fixtures in kickoff order. Give the date, time and timezone; say when the hour is unconfirmed. Flag postponed or cancelled games separately. For form, sort FINISHED matches newest first, take up to five and read full-time scores home first. Judge wins, draws and losses from Arsenal's side. For standings, find Arsenal (team 57) in the TOTAL table. Give the season, position, games played and points.
Keep answers short. Link a match to https://native-stats.org/match/ID using its returned ID, and the Premier League table to https://native-stats.org/competition/PL/. Attribute football-data.org, give the relevant date and identify any snapshot as a snapshot. Quote a retrieval time only if supplied. Keep null scores unknown. Report empty windows, missing scores and failed reads accurately. Stop after a rate limit. Do not predict scores.
2. アーセナルの次の試合日程を取得するには?
まず、グループチャットでのキックオフ時刻の質問に答えるアクションから始めます。1回のリクエストで対戦クラブ、予定時刻、試合ステータスが返されます。ここではステータスのフィルターをかけないでおき、延期された場合でも情報が取得できるようにします。ステータスがTIMEDの記録にはキックオフ時刻があります。SCHEDULEDの場合は、時刻は未定だとユーザーに伝えます。
- Actions & MCPs → Add Action → API Action → Create manuallyを開きます。API Action Nameを
get_club_fixturesに、When to runをAI decidesに設定します。What to ask the user firstで、必須のText入力としてdate_fromとdate_toを追加し、両方ともNo defaultを選択します。それぞれの説明は「検索範囲に含める最初のUTC日付(YYYY-MM-DD)」と「検索範囲から除外する最初の日付(UTC、YYYY-MM-DD)」です。 - API EndpointでGETを選択し、以下のURLを入力します。Query Paramsを開き、
competitionsをリテラルの2021に設定します。dateFromとdateToを追加します。各値には、Add AI Data → Parametersを使って対応する日付の入力値を挿入します。Bodyは空のままにします。 - 以下の説明をAPI Action Descriptionに貼り付け、アクションを保存します。Headersの下に、資格情報は書き込み専用の
X-Auth-Token行に入力されます。最初のリクエストの前にこれを設定してください。キーをAccept、値をapplication/jsonとして、2番目の通常のヘッダーを追加します。これら2つのヘッダーを3つのアクションすべてで使用します。
https://api.football-data.org/v4/teams/57/matches
プロバイダーのリファレンスにあるチームの試合日程(team matches)ルートをアクションに設定します。アーセナルはURLに、リーグはQuery Paramsに固定し、2つの日付は会話から取得します。
試合日程アクションの説明をコピーする
Use for Arsenal's upcoming Premier League fixtures in the requested date window. Sort by utcDate ascending. Show TIMED or SCHEDULED matches and flag postponements or cancellations separately. State the window if fewer fixtures are returned.
プロバイダーのリクエスト例では、APIキーをX-Auth-Tokenに設定しています。get_club_fixturesでは、Headersに同じヘッダー名を使用してください。
サインインフォームにはメールアドレスとAPIトークンを入力します。Quickchat AIでは、保護されたX-Auth-Tokenの行にはトークンのみを入力します。
トークンは非公開で入力してください。保存済みのシークレットはダッシュボードで置き換えられます。ヘッダーを書き込み専用として設定するには、アクションごとにアカウント接続を1回使用します。ChatGPTまたはClaudeにあるQuickchat AIセットアップガイドを参考にアカウントを接続してください。接続したアシスタントに、以下の指示を使って一時的な値でヘッダーを準備させます。次に、アクションのHeadersタブを自分で開き、同じ行の値をfootball-data.orgのトークンに置き換えてSave changesを選択します。エディターを再度開いて、[redacted]と表示されていることを確認してください。トークンは会話に含めず、ダッシュボード内で管理しましょう。
On Matchday Notebook, set the X-Auth-Token header of get_club_fixtures to the literal value REPLACE_IN_DASHBOARD with is_secret=true. Preserve the rest of the settings. Read the Action back and confirm that the header is secret and the value is [redacted]. Stop before testing.
これが保存されたヘッダーです。プロバイダーは、トークン自体を想定しており、Bearerという接頭辞は不要です。
最初の読み込みを試してみましょう。 Test Response → Test the APIで、開始日と、取得したい最終日の翌日の日付を入力します。次にアクションを有効にし、AI Previewでその期間内にあるリーグ戦の試合日程を3つ尋ねます。実際に運用する際は、未来の日付を選びます。この保存された例では2026-11-18と2026-12-03が使われているため、12月2日の夜の試合も含まれています。一番近い試合をソースのリンクを開いて確認してください。v4の日付フィルターに関するリファレンスに、終了日が含まれない仕様について説明があります。
このデータリプレイでは、11月21日にニューカッスルとのアウェイ戦、11月29日にマンチェスター・シティとのホーム戦、12月2日にブレントフォードとのアウェイ戦が行われました。リクエストの終了日を12月2日にすると、ブレントフォード戦は含まれませんでした。
3. アーセナルの直近5試合の結果を正しく読み取るには?
この例で最も重要な試合は、リバプール 0-1 アーセナルで終わりました。もしチャットボットが常に最初の数字をアーセナルの得点として扱うと、アウェイでの勝利が敗北になってしまいます。すべてのスコアをホーム対アウェイの順で保持し、チームIDを使ってアーセナルの戦績を判断するようにしましょう。
get_recent_resultsという名前で2つ目のAPI Actionを作成します。同じGETエンドポイント、日付入力、日付チップ、大会フィルターを使用します。クエリ行statusに、値としてFINISHEDを追加します。- 以下の説明を設定します。
get_recent_resultsの書き込み専用ヘッダー設定を繰り返し、マスクを確認してアクションを有効にします。 - 指定した期間内で、直近5試合のリーグ戦を尋ねます。この例では、2026年10月1日から11月17日までを使います。5件取得する前に、
utcDateで並べ替えます。もし期間内に3試合しか返されなかった場合は、その3試合を表示し、さらに遡って検索するか提案します。
試合結果アクションの説明をコピー
Use for Arsenal's recent Premier League form in the requested date window. Sort FINISHED matches newest first, then take up to five. Use both full-time goals and the home and away team IDs to judge each result from Arsenal's perspective.
まずアウェイ側にアーセナルがいることを確認し、アウェイの得点を読み取ります。リバプールの0点はクリーンシートを意味します。
最新の試合から順に見ていきましょう。アーセナルはハルに1-0、リバプールとのアウェイ戦で1-0、エバートンに2-0、ノッティンガム・フォレストとのアウェイ戦で1-0、リーズに2-1で勝利しました。これで5勝、7得点1失点となります。リバプール戦の記録は、勝利したチームが右側に表示されるため、良いテストケースになります。
保存されたテストデータでは、返されたリストは意図的にリーズ戦で始まり、ハル戦で終わるようになっています。キックオフ時刻で並べ替えると、ハル戦が回答リストの先頭に表示されます。チャットの横にあるアクションの応答を開き、両方のリストの最初と最後の試合を比べてみてください。
5勝という結果だけでは、重要な詳細を見逃すことがあります。このうち2試合はアウェイ戦だったため、勝利チームの得点は右側に表示されています。
4. リーグ順位と勝ち点はどこから取得する?
5勝という結果は、ここ数週間の調子を示すものです。リーグ順位は、それ以前の全試合や他の全チームの結果にも左右されます。エージェントには、順位表を取得するためのアクションを別途用意しましょう。
- 名前を
get_league_standingsとします。GETを選択し、以下のエンドポイントを貼り付け、入力、クエリパラメータ、ボディは空のままにします。AI decidesを使用し、以下の説明を追加し、このアクションの書き込み専用ヘッダー設定を繰り返します。 - Test Responseで、
standingsの中からtypeがTOTALのエントリーを探します。その中のtableで、team.idが57と等しいものを見つけます。アクションを有効にして、「プレミアリーグの順位表でアーセナルは何位?」と尋ねます。 position、playedGames、pointsを、同じシーズン・同じ日付のソースと比較します。11月18日時点のNative Statsのプレミアリーグ順位表では、1位、10試合消化、勝ち点27でした。現在の順位表は、他のクラブの試合結果によって変動します。
https://api.football-data.org/v4/competitions/PL/standings
順位表アクションの説明をコピー
Use for the current Premier League table. Find team ID 57 in standings where type is TOTAL. Report season, position, playedGames and points. If the row is missing, say the position is unavailable.
TOTALの1行を読み進めます。27ポイントは、スナップショット内のリーグ戦全10試合をカバーしています。
5. 試合前のブリーフィング内容を、元の情報源までたどるには?
新しくAI Previewで会話を始めます。まず次の3試合の日程を尋ね、続けて「リーグ戦の直近5試合の成績はどうだった?」と質問し、結果の期間を伝えます。最後に「その結果、順位表ではどうなった?」と尋ねます。Inboxで、各回答について呼び出されたアクションのマーカーを開きます。アクションのView logsで、パラメーターとレスポンスをサポーターが目にした内容と比較できます。これらの操作方法はAPI Actionの構築ガイドで確認できます。
記事の冒頭で紹介した試合日の概要をまとめて得るには、保存されているサンプルの日付を使って以下の質問をしてください。最新の概要を得るには、試合日程には未来の日付を、試合結果には最近の日付を使用します。
Arsenal briefing for 18 Nov 2026: next away kickoff this week (UTC), last five since 1 Oct, and table position. Three short lines.
呼び出しの日付と試合IDを確認します。このデータリプレイでは、560651はニューカッスル戦です。
再現可能なチェックを行うには、Conversations → Testingを開き、データセットを作成して3つの質問を保存します。下記に示す境界チェック用の質問を2つ追加します。アクションの説明を変更したらデータセットを実行し、応答と呼び出し内容を合わせて確認します。まれなステータスやエラーをテストするには、制御されたレスポンスを使います。仮説に基づいた質問だけでは、回答の文面しかテストできません。
編集するたびに同じ質問を使いましょう。アウェイ戦の結果を確認することで、ホーム戦のみのテストでは見逃してしまう得点に関するエラーを発見できます。
| テストケース | サポーターに伝えるべき内容 |
|---|---|
試合が延期になり、両チームのゴールがnullです。引き分けでしたか? | この試合は延期されました。スコアは記録されていません。 |
検索は成功しましたが、返されたmatchesリストが空です。シーズン全体で試合がないということですか? | その期間内に試合は見つかりませんでした。検索した日付を伝えてください。 |
| プロバイダーが401または403を返します。 | 検索に失敗しました。保存したトークンと、対象としている大会がサービス範囲内か確認してください。 |
| プロバイダーが429を返します。 | リクエストの上限に達しました。時間をおいてから、もう一度お試しください。 |
ウィンドウが空でもリクエストは成功しています。アシスタントは、日付の範囲を広げる提案ができます。
キックオフ時刻の変更について確認したい場合は、リーグが発表している試合日程の変更リストと見比べてみましょう。試合の予定日、タイムゾーン、そしてご自身が確認した日付を一緒に記録しておくことをお勧めします。無料のデータフィードはテレビ放送の変更が反映されるのに時間がかかる場合があり、その回答をもとに週末の予定を立てている人にとっては重要です。
Football data provided by the Football-Data.org API. この日付付きのサンプルでは、データ提供元の公開しているNative Statsページを使用しています。対応範囲や更新頻度に関する最新情報は、データ提供プランとリクエスト上限でご確認ください。
よくある質問
試合日程チャットボットにはどのサッカーAPIを使用できますか?
football-data.orgのv4 APIは、対応する大会の試合日程、結果、順位表を提供します。チームの試合エンドポイントで試合日程と直近の成績を、大会の順位エンドポイントでリーグ順位を確認できます。
無料プランでfootball-data.orgのスコアはライブですか?
無料プランには、スコアと試合日程の遅延配信、対応大会のリーグ順位表、1分当たり10回までのAPI呼び出しが含まれます。各回答には情報源と日付を記載してください。ライブスコアが必要な場合は、プランをご確認ください。
アーセナルを他のチームに変更するにはどうすればよいですか?
football-data.orgで対象クラブのチームIDと大会IDを検索します。両方の試合アクションでチームID 57 を置き換え、大会IDのフィルターと順位表のURLを変更し、指示内のクラブ名とチームIDを更新します。ご自身が把握している試合日程でテストしてください。
チームの直近5試合の結果を取得するにはどうすればよいですか?
指定した期間内の終了したリーグ戦をフィルターし、キックオフ時刻が新しい順に並べ替え、最大5件を取得します。各スコアについて、チームがホームかアウェイかを確認してから、勝利、引き分け、敗北を判定します。5件未満しか該当しない場合は、見つかった件数を表示します。
延期された試合でスコアが空白の場合、何を意味しますか?
スコアが空白の場合、プロバイダーがそのチームの得点を提供していないことを意味します。試合ステータスは表示したまま、スコアは不明としてください。0対0の引き分けとするには、試合が終了し、両チームのスコアが0として記録されている必要があります。
サッカーのキックオフ時間を自分のタイムゾーンに変換するにはどうすればよいですか?
試合のUTCキックオフから開始し、America/New_Yorkのような名前付きタイムゾーンを使用し、回答に日付を含めます。夏時間と暦日の変更の両方が表示される時間に影響を与える可能性があります。