Build a goal alert bot
A message in your Telegram chat or Discord channel the moment a goal goes in, for every match in play. One API call a minute.
What the bot sends
Sample output: the alerts for six real goals, built from the API's own JSON. The sample was captured with an Ultra key, which returns every league; a free key returns the top-5 leagues.
Goal alerts
bot
GOAL 30' FK Alga 2-1 FC Asiagoal
Kyrgyzstan Top Liga
GOAL 30' Blacks Power 0-2 Vipers SC
Uganda Premier League
GOAL 45' Mohun Bagan SG 1-0 East Bengal Club
India IFA Shield
GOAL 18' Pamba SC 2-0 Geita Gold
Tanzania Premier League
GOAL 34' Uganda (W) 1-1 Zambia (W)
Womens Olympic Qual
GOAL 37' Ferroviario Maputo 1-0 Vilankulo FC
Mozambique Mocambola
6 goals from the 36 matches in play at 13:37 UTC on 8 October 2026. Sample built from
GET /v1/fixtures?status=live&include=events
The API calls behind it
-
1
GET /v1/fixtures?status=live&per_page=500Every match in play right now, with its current score. The bot compares each score with the one it saw a minute ago. Reference →
What it takes to run
- The free plan returns live matches from the top-5 leagues — no card needed.
- One request a minute, whatever the number of matches. That is 60 requests an hour; the free plan allows 60 requests / hour.
- Pro at $5/mo widens it to 130+ competitions at 10 requests / min, enough to poll every 10 seconds.
The code
Install the client, save the script, run it with your key.
pip install fivedollarfootball requestsimport os
import time
import requests
from fivedollarfootball import Client
client = Client(os.environ["FIVEDOLLARFOOTBALL_API_KEY"])
def notify(text):
"""Send to whichever of Telegram and Discord is configured."""
if os.environ.get("TELEGRAM_BOT_TOKEN"):
requests.post(
f'https://api.telegram.org/bot{os.environ["TELEGRAM_BOT_TOKEN"]}/sendMessage',
json={"chat_id": os.environ["TELEGRAM_CHAT_ID"], "text": text}, timeout=10,
)
if os.environ.get("DISCORD_WEBHOOK_URL"):
requests.post(os.environ["DISCORD_WEBHOOK_URL"], json={"content": text}, timeout=10)
print(text, flush=True)
scores = {} # fixture id -> (home goals, away goals) at the last poll
while True:
# One call: every match in play right now.
for m in client.fixtures(status="live", per_page=500):
score = (m["goals"]["home"] or 0, m["goals"]["away"] or 0)
before = scores.get(m["id"])
# The first time a match is seen only sets its baseline.
if before is not None and sum(score) > sum(before):
minute = "HT" if m["status_code"] == "half" else f'{m["status_code"]}\''
notify(f'GOAL {minute} {m["teams"]["home"]["name"]} {score[0]}-{score[1]} '
f'{m["teams"]["away"]["name"]} ({m["league"]["name"]})')
scores[m["id"]] = score
time.sleep(60)
FIVEDOLLARFOOTBALL_API_KEY=fb_live_your_key DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/... python goal_bot.pyThe full project is on GitHub: 5dollarfootball-api/football-goal-alert-bot →
Take it further
- Discord: create a webhook in the channel settings and set DISCORD_WEBHOOK_URL. Telegram: create a bot with @BotFather and set TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID.
- Compare m["corners"] the same way to alert on corners, or on a match reaching a corner count.
- Compare m["cards"] to alert on red cards.
- Add include=["events"] to the call to get the minute of each goal from the match timeline.
- Pass league=id to follow one competition only.
The data behind this example
Frequently asked questions
Yes. The bot makes one request a minute whatever the number of matches, which is 60 requests an hour. The free plan allows 60 requests / hour, returns live matches from the top-5 leagues and needs no card.
As fast as you poll. The script asks once a minute, so an alert arrives within about a minute of the score changing in the feed. On Pro, at 10 requests / min, the same script can poll every 10 seconds.
Yes. It posts to whichever is configured: a Discord channel through a webhook address, a Telegram chat through a bot token and a chat id. Set both and it posts to both.
Start building for free
Get a working API key in under a minute. No credit card, no sales call.