Runs on the free plan Python 1 API call

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.

G

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. 1
    GET /v1/fixtures?status=live&per_page=500

    Every 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.
Compare plans

The code

Install the client, save the script, run it with your key.

pip install fivedollarfootball requests
import 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.py

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

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.