Skip to content

Home

Jump to bottom
Aarón Gallardo Canto edited this page May 14, 2025 · 2 revisions

GolBot - Technical Documentation Wiki

Overview

GolBot is a Telegram bot that provides real-time information about football matches, standings, and top scorers from major European leagues such as LaLiga, Premier League, Serie A, Bundesliga, and the Champions League. It uses a football API (private token required) to fetch up-to-date data and presents it in a simple, user-friendly format.

Architecture and Code Structure

  • Main libraries:

    • requests: For making HTTP requests to the external API.
    • telebot (PyTelegramBotAPI): For interacting with Telegram and handling messages/commands.
    • datetime and pytz: For managing dates and timezones (configured to Europe/Madrid).

  • Key variables:

    • API_KEY: Token to authenticate with the football API.
    • BASE_URL: Base URL of the football API.
    • bot: TeleBot instance initialized with the Telegram bot token.
    • tz: Timezone set to "Europe/Madrid".

  • COMPETICIONES dictionary: Defines supported leagues with their API codes, display names, and representative emojis.

Main Features

Telegram Commands and Handlers

  • /start Sends a welcome message and explains how to use the available commands.

  • /partidos <league> <today|matchday> Shows matches from the specified league for today or the upcoming matchday. Example: /partidos laliga today

  • /clasificacion <league> Shows the current standings table of the chosen league.

  • /maximos <league> Shows the top scorers of the specified league.

Key Function Descriptions

obtener_partidos_jornada(codigo_competicion, modo="hoy")

  • Requests all matches of the competition from the API.

  • Filters matches based on mode:

    • "hoy" (today): matches scheduled for the current day.
    • "jornada" (matchday): matches in the next pending (unfinished) matchday.

  • Returns formatted text ready to send via Telegram.

formatear_partido(partido)

  • Takes a match JSON object and returns a user-friendly text including:

    • Local date and time (Europe/Madrid timezone).
    • Home and away teams.
    • Match status and final score if finished.

obtener_clasificacion_liga(codigo_competicion)

  • Fetches the league standings from the API.
  • Builds a ranked list with position (using emojis), team name, and points.

obtener_maximos(codigo_competicion)

  • Retrieves top scorers for the league from the API.
  • Lists the top 5 scorers with player name and goals scored.

Error Handling and Validation

  • Validates user command input to ensure required parameters are provided.
  • Checks if the league exists in the COMPETICIONES dictionary.
  • Handles API errors when responses have non-200 status codes.
  • Sends clear user messages in case of errors or unavailable data (e.g., "No matches today", "Invalid league").

Running and Deployment

To run the bot:

  1. Insert your Telegram bot token into the telebot.TeleBot() call (already included in the code).
  2. Insert your football API token into API_KEY.
  3. Set the API base URL in BASE_URL.
  4. Run the Python script. The bot will remain active, listening and responding to commands with bot.polling(none_stop=True).

Clone this wiki locally