Skip to content

Home

Jump to bottom
Aarón Gallardo Canto edited this page May 23, 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).

GolBot DevLog – Daily Development

March 10 – Project Kickoff and Basic Setup

  • Created the repository and initial Python environment.
  • Set up the Telegram bot using the telebot library.
  • Implemented the /start command with a welcome message and list of supported leagues.
  • Defined the COMPETICIONES dictionary with main leagues and their API codes.
  • Configured Madrid timezone with pytz for date handling.

March 11 – Added Feature to Show Today’s Matches

  • Developed /partidos [league] hoy command to fetch matches scheduled for today.
  • Integrated external API using requests with authentication token.
  • Formatted messages including date, teams, and match status.
  • Basic error handling: invalid league and API call failures.
  • Local testing and initial deployment.

March 12 – Extended to Show Next Matchday’s Fixtures

  • Added support for /partidos [league] jornada to display the next upcoming matchday’s games.
  • Logic to automatically detect the next active matchday based on match statuses.
  • Clear messages when no upcoming matchdays are available.
  • Special validation for Champions League disabling “jornada” option after group stage ended.

March 13 – Implemented /clasificacion Command

  • Created /clasificacion [league] command to show the current league standings table.
  • Parsed classification data from API response.
  • Added emoji system for highlighting positions (medals and numbers).
  • Input validation and error messages if league not found or API failure.

March 14 – Initial Max Scorers Feature

  • Basic implementation of /maximos [league] showing top five goal scorers.
  • Flexible handling of different JSON fields (numberOfGoals vs goals).
  • Error messages for no data or invalid league input.
  • Internal logging for JSON structure debugging.

March 15 – Presentation and UX Improvements

  • Improved date formatting to dd/mm/yyyy HH:mm for better clarity.
  • Added emojis in match formatting to indicate match status (finished, in play, etc).
  • Visual separators between matches to enhance readability.
  • Enriched welcome messages with emojis to make it friendlier.

March 16 – Robustness and Validations

  • Added controls to handle incorrectly written commands or missing parameters.
  • Automatic replies guiding users on how to correctly use commands.
  • Refactored functions to avoid code duplication, especially in match retrieval and formatting.
  • Improved HTTP error management and user-facing messages on API failures.

March 17 – Deployment Preparation and Maintenance

  • Incorporated bot.remove_webhook() and bot.polling(none_stop=True) for stability.
  • Final code cleanup and descriptive comments.
  • Initial documentation and usage examples for users.
  • Planned future features: top assistants, automatic notifications, and UI improvements with inline buttons.

Clone this wiki locally