---
title: "Build a Football Chatbot for Fixtures, Form and Standings"
pubDate: 2026-11-18
description: "Build an Arsenal matchday chatbot with Quickchat AI and the football-data.org API. Get the next kickoff, read the last five results and check the league table."
author:
  name: "Piotr Grudzień"
  image: "/blog-assets/authors/piotr_grudzien.jpg"
image:
  url: "/blog-assets/posts/football-fixtures-form-assistant-v3_bg.webp"
  alt: "Arsenal’s three-line matchday briefing in Quickchat AI alongside football-data.org Account Settings showing a Free subscription"
tags: ["tutorials", "engineering"]
articleCta:
  title: "Build a matchday notebook for your club"
  subtitle: "Start with one fixture you can check, then add recent results and the league table."
  button: "Create your football chatbot"
  href: "https://app.quickchat.ai/register"
  note: "You need a football-data.org token for current fixtures. The downloadable example works offline."
faq:
  - question: "Which football API can I use for a fixtures chatbot?"
    answer: "The football-data.org v4 API supplies fixtures, results and standings for covered competitions. Use the team’s matches endpoint for the schedule and recent form, and the competition’s standings endpoint for league position."
  - question: "Are football-data.org scores live on the free plan?"
    answer: "The free plan includes delayed scores and schedules, league tables for covered competitions and 10 API calls per minute. Include the source and date with each answer and check your plan if you need live scores."
  - question: "How do I change Arsenal to another team?"
    answer: "Find the club’s team ID and competition in football-data.org. Replace team 57 in both match Actions, change the numeric competition filter and standings URL, then update the club name and team ID in the instructions. Test against a fixture you recognize."
  - question: "How do I get the last five matches from the team’s point of view?"
    answer: "Filter for finished league matches in a specified date window, sort by kickoff from newest to oldest and take up to five. For each score, check whether your team played at home or away before assigning a win, draw or loss. If fewer than five qualify, show how many you found."
  - question: "What does a blank score mean for a postponed match?"
    answer: "A blank score means the provider has supplied no goal total for that side. Keep the match status visible and leave the score unknown. A goalless draw needs a finished match with two recorded zeroes."
  - question: "How do I convert a football kickoff to my time zone?"
    answer: "Start with the match’s UTC kickoff, use a named time zone such as America/New_York and keep the date in the answer. Daylight saving and a change of calendar day can both affect the displayed time."
howto:
  - name: "Which club and competition will the chatbot follow?"
    text: "Get your football-data.org API token, choose a covered club and competition, and add the Matchday Notebook instructions to a private Quickchat AI Agent."
  - name: "How do you get the next Arsenal fixture?"
    text: "Configure get_club_fixtures with team 57, competition 2021, a start date, an exclusive end date and a write-only X-Auth-Token header. Use Test Response to check the kickoff."
  - name: "How do you read the last five results from Arsenal’s side?"
    text: "Add get_recent_results with status FINISHED. Sort by kickoff from newest to oldest and read up to five scores, checking whether Arsenal played at home or away."
  - name: "Where do the league position and points come from?"
    text: "Use get_league_standings to find team 57 in the TOTAL table and read its position, games played and points."
  - name: "Can you trace the matchday briefing back to its sources?"
    text: "Ask the three matchday questions in AI Preview and compare each answer with its Action call in Inbox. Use controlled responses to check an empty window and a postponed match."
---

You’re arranging Saturday around Arsenal’s trip to Newcastle. A friend in New York needs the kickoff time. Then someone in the group chat asks how Arsenal did on their last trip away. The first answer is sitting in a fixture list. For the second, you need to know whose goal the 1 in “Liverpool 0, Arsenal 1” belongs to.

You’ll build **Matchday Notebook**, a football chatbot that looks up the next three Premier League fixtures, reads Arsenal’s last five league results and finds their place in the table. The example is pinned to **18 November 2026**. Newcastle away was due on **Saturday, 21 November at 17:30 UTC**, or **12:30 p.m. in New York**.

<div class="tutorial-screen tutorial-panel">

![The Newcastle fixture in Native Stats and the corresponding matchday answer in Quickchat AI](../../assets/blog/posts/matchdayNotebook/finish-line.webp)
*The provider’s match page and the private Agent agree on the kickoff. The Quickchat AI conversation ran against a dated replay of public records, which you can reproduce below.*

</div>

[Check the Newcastle fixture](https://native-stats.org/match/560651) or [download the Matchday Notebook kit](/blog-assets/downloads/matchday-notebook.zip). Unzip it and run `python3 replay.py` to see the three fixtures, five results and table row without an account. The same kit includes the Action settings and Main Prompt for connecting your own feed.

<a id="choose-club"></a>
## 1. Which club and competition will the chatbot follow?

Pin the club and league first. Arsenal’s league form can change depending on whether you count a Tuesday night in Europe. In this notebook **Arsenal means team `57`** and **league means Premier League `2021`**, also known by its code `PL`.

1. Open the [football-data.org registration form](https://www.football-data.org/client/register). Enter your first name and email address, accept the terms and select **Create account**. Check your league on the [coverage list](https://www.football-data.org/coverage). The free plan includes the Premier League, with delayed fixtures and scores.

<div class="tutorial-screen tutorial-panel">

![The football-data.org registration form with its first-name and email fields, Create account button and Free Tier details](../../assets/blog/posts/matchdayNotebook/provider-account-setup.webp)
*Use an email address you can check. football-data.org sends the API key there after registration. The free plan allows 10 requests per minute.*

</div>

If you already have an account, [sign in](https://www.football-data.org/client/login) with your email and API token. If you need another copy of the token, [request it by email](https://www.football-data.org/client/forgotToken) using the address you registered. Keep the token for the [protected header in Step 2](#fixture-action).

<div class="tutorial-screen tutorial-panel">

![football-data.org Account Settings showing a Free subscription and part of the Available competitions list](../../assets/blog/posts/matchdayNotebook/provider-account-overview.webp)
*Check your plan under **Subscription** and look for your league under **Available competitions**. This excerpt shows the UEFA Champions League (CL) and Bundesliga (BL1).*

</div>

2. To follow another club, look it up in the competition’s teams list, for example `GET /v4/competitions/PL/teams`. Use the returned team ID and competition ID in the match requests below. The [v4 quickstart](https://www.football-data.org/documentation/quickstart) has both lookups.
3. [Create a Quickchat AI Agent](https://app.quickchat.ai/register), name it **Matchday Notebook**, and keep it private while you test. You need available credits for conversations and simulations. Open **Identity → AI Persona → Main Prompt** and paste the instructions below. The screenshots and copyable settings use English.

<div class="tutorial-screen tutorial-panel">

![Arsenal’s club page in Native Stats and Matchday Notebook’s Identity settings in Quickchat AI](../../assets/blog/posts/matchdayNotebook/club-and-identity.webp)
*Keep the same club in both places. In the product, the Agent’s instructions live under Identity.*

</div>

<details class="tutorial-artifact">
<summary>Copy the Matchday Notebook Main Prompt</summary>

```text
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.
```

</details>

<a id="fixture-action"></a>
## 2. How do you get the next Arsenal fixture?

Start with the Action that answers the group chat’s kickoff question. One request returns both clubs, the scheduled time and the match status. Leave the status filter open here so a postponement can still surface. A `TIMED` record has a kickoff time. For `SCHEDULED`, tell the reader the hour is still to be confirmed.

1. Open **Actions & MCPs → Add Action → API Action → Create manually**. Set **API Action Name** to `get_club_fixtures` and **When to run** to **AI decides**. Under **What to ask the user first**, add the required **Text** inputs `date_from` and `date_to`, both with **No default**. Their descriptions are “First UTC date to include, YYYY-MM-DD” and “First UTC date to exclude, YYYY-MM-DD”.
2. For **API Endpoint**, choose **GET** and enter the URL below. Open **Query Params** and set `competitions` to the literal `2021`. Add `dateFrom` and `dateTo`. For each value, use **Add AI Data → Parameters** to insert the matching date input. Leave **Body** empty.
3. Paste the description below under **API Action Description** and save the Action. Under **Headers**, the credential will go in a write-only `X-Auth-Token` row. Set that up before your first request. Add a second, ordinary header with `Accept` as the key and `application/json` as the value. Use the same two headers on all three Actions.

```text
https://api.football-data.org/v4/teams/57/matches
```

<div class="tutorial-screen tutorial-panel">

![The football-data.org Team matches route and the Quickchat AI GET endpoint with Query Params for competition 2021 and two dates](../../assets/blog/posts/matchdayNotebook/fixture-editor.webp)
*Follow the team matches route from the provider reference into the Action. Arsenal is fixed in the URL, the league in Query Params, and the two dates come from the conversation.*

</div>

<details class="tutorial-artifact">
<summary>Copy the fixture Action description</summary>

```text
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.
```

</details>

The [provider’s request examples](https://docs.football-data.org/general/v4/coding_client.html#_sample_requests) put the API key in `X-Auth-Token`. Use that same header name in **Headers** on `get_club_fixtures`.

<div class="tutorial-screen tutorial-panel">

![The public football-data.org Sign in form, the v4 X-Auth-Token example and the Headers tab in Quickchat AI](../../assets/blog/posts/matchdayNotebook/provider-api-to-quickchat.webp)
*The sign-in form takes your email and API token. In Quickchat AI, only the token goes in the protected `X-Auth-Token` row.*

</div>

**Enter the token privately.** The dashboard can replace a saved secret. To make that header write-only in the first place, use the account connection once per Action. Connect your account using the [Quickchat AI setup guide](https://quickchat.ai/docs/manage-with-ai) in [ChatGPT](https://chatgpt.com/plugins/plugin_asdk_app_6a4656c688748191be4c5247fb0d5dfc) or [Claude](https://claude.ai/directory/connectors/app-quickchat-ai). Ask the connected assistant to prepare the header with a harmless marker using the instruction below. Then open the Action’s **Headers** tab yourself, replace the value in that **same row** with your raw football-data.org token, and select **Save changes**. Reopen the editor and check that it displays `[redacted]`. Keep the token in the dashboard and out of the conversation.

```text
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.
```

<div class="tutorial-screen tutorial-panel">

![Headers in the fixture Action showing X-Auth-Token with a redacted value](../../assets/blog/posts/matchdayNotebook/secret-header.webp)
*This is the saved header. The provider expects the token by itself, without a Bearer prefix.*

</div>

**Try the first read.** In **Test Response → Test the API**, supply a start date and the day *after* your last desired date. Then enable the Action and ask in **AI Preview** for the next three league fixtures in that window. For a live build, choose upcoming dates. The archive example used `2026-11-18` and `2026-12-03`, so the evening of 2 December counted. Check the nearest match by opening its source link. The [v4 date-filter reference](https://docs.football-data.org/general/v4/index.html) explains the exclusive end date.

<div class="tutorial-screen tutorial-panel">

![Three fixture dates between the inclusive start on 18 November and the exclusive end on 3 December](../../assets/blog/posts/matchdayNotebook/fixtures-window.webp)
*In the replay, Newcastle away fell on 21 November, Manchester City at home on 29 November and Brentford away on 2 December. Ending the request on 2 December would have dropped Brentford.*

</div>

<a id="recent-form"></a>
## 3. How do you read the last five results from Arsenal’s side?

The most revealing game in this example finished **Liverpool 0, Arsenal 1**. If the chatbot treats the first number as Arsenal’s score every time, it turns an away win into a defeat. Keep every score in home-away order and use the team ID to decide how Arsenal did.

1. Create a second API Action named `get_recent_results`. Use the same GET endpoint, date inputs, date chips and competition filter. Add the query row `status` with the literal value `FINISHED`.
2. Set the description below. Repeat the write-only header setup for `get_recent_results`, check the mask and enable the Action.
3. Ask for the five most recent league games in a stated window. For the example, use 1 October through 17 November 2026. Sort by `utcDate` before taking five. If the window returns only three, show those three and offer to look further back.

<details class="tutorial-artifact">
<summary>Copy the results Action description</summary>

```text
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.
```

</details>

<div class="tutorial-screen tutorial-panel">

![Liverpool 0, Arsenal 1 on the source match page with the Arsenal away score picked out](../../assets/blog/posts/matchdayNotebook/away-result.webp)
*First find Arsenal on the away side, then read the away goal. Liverpool’s zero is the clean sheet.*

</div>

**Read the run newest first.** Arsenal beat Hull 1–0, won 1–0 at Liverpool, beat Everton 2–0, won 1–0 at Nottingham Forest and beat Leeds 2–1. That makes **five wins, seven goals for and one against**. The [Liverpool match record](https://native-stats.org/match/560631) makes a good test because the winning side appears second.

The replay deliberately returned Leeds first and Hull last. Sorting the timestamps put Hull first in the reply. Open the Action response alongside the conversation and check both ends of the list.

<div class="tutorial-screen tutorial-panel">

![Five finished Arsenal matches shown in date order with the home and away scores](../../assets/blog/posts/matchdayNotebook/form-run.webp)
*Five wins can hide an important detail. Two of these were away, so the winning number is on the right.*

</div>

<a id="league-table"></a>
## 4. Where do the league position and points come from?

Five wins tell you how the last few weeks went. League position also depends on all the matches before them and everyone else’s results. Give the Agent a separate standings Action.

1. Name it `get_league_standings`. Choose **GET**, paste the endpoint below and leave the inputs, query parameters and body empty. Use **AI decides**, add the description below and repeat the write-only header setup for this Action.
2. In **Test Response**, look in `standings` for the entry whose `type` is `TOTAL`. Within its `table`, find `team.id` equal to `57`. Enable the Action and ask “Where are Arsenal in the Premier League table?”
3. Compare `position`, `playedGames` and `points` with the source for the same season and date. On 18 November the [Premier League table in Native Stats](https://native-stats.org/competition/PL/) showed **1st, 10 played, 27 points**. Your current table will move as other clubs play.

```text
https://api.football-data.org/v4/competitions/PL/standings
```

<details class="tutorial-artifact">
<summary>Copy the standings Action description</summary>

```text
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.
```

</details>

<div class="tutorial-screen tutorial-panel">

![Arsenal’s first-place row in the Premier League standings and the fields used by the notebook](../../assets/blog/posts/matchdayNotebook/table-proof.webp)
*Read across a single row in TOTAL. The 27 points cover all ten league matches in the snapshot.*

</div>

<a id="test-notebook"></a>
## 5. Can you trace the matchday briefing back to its sources?

Start a fresh **AI Preview** conversation. Ask for the next three fixtures, follow up with “How did we do in our last five league games?”, give the results window, then ask “Where does that leave us in the table?” In **Inbox**, open the called-Action marker for each answer. The Action’s **View logs** lets you compare the parameters and response with what the supporter saw. The [guide to building an API Action](https://quickchat.ai/post/build-an-ai-agent-that-takes-actions) shows where to find these controls.

To reproduce the single briefing at the top, use the following question with the replay dates. For a current briefing, substitute upcoming and recent dates.

```text
Arsenal briefing for 18 Nov 2026: next away kickoff this week (UTC), last five since 1 Oct, and table position. Three short lines.
```

<div class="tutorial-screen tutorial-panel">

![The fixture Action call in Quickchat AI with its request and returned match record](../../assets/blog/posts/matchdayNotebook/call-detail.webp)
*Inspect the dates and match ID in the call. In the local replay, 560651 is the Newcastle fixture.*

</div>

For a repeatable check, open **Conversations → Testing**, create a dataset and save the three questions. Add the two boundary questions shown below. Run the dataset after changing an Action description and inspect the calls alongside the replies. Use a controlled response to exercise a rare status or an error. A hypothetical question alone tests the wording of an answer.

<div class="tutorial-screen tutorial-panel">

![The Matchday Notebook dataset in Quickchat AI containing fixture, form, table and boundary questions](../../assets/blog/posts/matchdayNotebook/testing.webp)
*Use the same questions after each edit. The away result catches a scoring error that an all-home test would miss.*

</div>

| Test case | What the supporter should hear |
| --- | --- |
| A match is postponed and both goals are `null`. Was it a draw? | The fixture was postponed. There is no recorded score. |
| A successful search returns an empty `matches` list. Is the whole season empty? | No matches were returned in that window. Give the dates you searched. |
| The provider returns 401 or 403. | The lookup failed. Check the saved token and competition coverage. |
| The provider returns 429. | The request limit was reached. Stop and try again later. |

<div class="tutorial-screen tutorial-panel">

![Quickchat AI’s empty-window answer paired with the successful request returning no matches](../../assets/blog/posts/matchdayNotebook/empty-window.webp)
*An empty window still has a successful request. The assistant can offer to widen the dates.*

</div>

For a second opinion on a changed kickoff, compare it with the league’s [published fixture amendments](https://www.premierleague.com/en/news/4725574). Keep the scheduled date, the time zone and the date you looked it up together. The free feed can lag behind a broadcast change, which matters when someone is planning their Saturday around the answer.

Football data provided by the Football-Data.org API. The dated example uses the provider’s public Native Stats pages. See the [feed plans and rate limits](https://www.football-data.org/pricing) for current coverage and freshness.

## Frequently asked questions

### Which football API can I use for a fixtures chatbot?

The football-data.org v4 API supplies fixtures, results and standings for covered competitions. Use the team’s matches endpoint for the schedule and recent form, and the competition’s standings endpoint for league position.

### Are football-data.org scores live on the free plan?

The free plan includes delayed scores and schedules, league tables for covered competitions and 10 API calls per minute. Include the source and date with each answer and check your plan if you need live scores.

### How do I change Arsenal to another team?

Find the club’s team ID and competition in football-data.org. Replace team 57 in both match Actions, change the numeric competition filter and standings URL, then update the club name and team ID in the instructions. Test against a fixture you recognize.

### How do I get the last five matches from the team’s point of view?

Filter for finished league matches in a specified date window, sort by kickoff from newest to oldest and take up to five. For each score, check whether your team played at home or away before assigning a win, draw or loss. If fewer than five qualify, show how many you found.

### What does a blank score mean for a postponed match?

A blank score means the provider has supplied no goal total for that side. Keep the match status visible and leave the score unknown. A goalless draw needs a finished match with two recorded zeroes.

### How do I convert a football kickoff to my time zone?

Start with the match’s UTC kickoff, use a named time zone such as America/New_York and keep the date in the answer. Daylight saving and a change of calendar day can both affect the displayed time.

---

Not answered on this page? Ask Quickchat AI directly: https://app.quickchat.ai/v1/api_core/public-question/quickchat/ask/?q=your+question&placement=www-markdown-footer-ask-v1&format=html
