How to create a bot that sends notifications about goals, corners, and cards?

What is a sports events API and how to use it to get goals, corners, and cards

A sports events API is a programming interface that provides access to data about matches, teams, and game details in a machine-readable format. In the case of football, this includes not only the score but also a list of live events: goals, yellow and red cards, corners, free kicks, and other actions on the field. On the platform api-sport.ru such data is available through a unified REST API for different sports, with each sport using its own slug (for example, football for football), which simplifies integration and scaling of the project.

Technically, access to information is built around a set of endpoints. For example, the method /v2/football/matches returns a list of matches with the current score, minute of the game (currentMatchMinute) and detailed statistics, while the method /v2/football/matches/{matchId}/events returns a chronological list of events, where each event is described by type (goal or card), time, and participants. It is these structures that allow the bot to learn in real-time about a new goal or card, and then send an instant notification to the user. For corners and other metrics, it is convenient to use the field matchStatistics, where there is a value of the metric for each team.

The main advantage of this approach is that the bot’s logic becomes as simple as possible: it periodically calls the API, receives a strictly structured JSON, analyzes the necessary fields, and decides whether to generate a notification. At the same time, the same API can be easily used for both simple alerts (only goals) and advanced scenarios: notifications for the N-th corner, a certain number of cards, or a combination of events. In the future, the platform api-sport.ru is developing not only REST but also WebSocket channels and AI tools, which will allow building even faster and smarter bot systems for betting, analytics, and media projects.

Overview of popular football APIs for goal notifications and match statistics

The market for football APIs is saturated today, but not every service is equally convenient for the tasks of notifications about goals, cards, and corners. Three parameters are critical for the bot: the depth of live data, update latency, and operational stability. On api-sport.ru live information is available through the field liveEvents in the match object (endpoints /v2/football/matches и /v2/football/matches/{matchId}) and through a separate method /v2/football/matches/{matchId}/events, which allows for quickly obtaining fresh events as well as restoring the full chronology of the match if necessary.

Below is an example of a request that can be used in the bot to get all current matches in progress and their events in one polling cycle. The API server is used as the host https://api.api-sport.ru, authorization is done via the header Authorization with your key from the personal account:

curl -X GET "https://api.api-sport.ru/v2/football/matches?status=inprogress" \
  -H "Authorization: YOUR_API_KEY"

The response contains an array матчи, in which for each match there are fields домашнийСчет, выезднойСчет, currentMatchMinute, an array liveEvents and a block matchStatistics. This combination allows the bot not only to know the fact of a goal but also to assess the context: how many corners have already been taken, how many cards have been shown, how the dynamics are changing. If you add to this the field oddsBase With bookmaker coefficients, it becomes possible to build bots for betting analytics and line comparison. Due to the unified data structure across different sports, the API from api-sport.ru is easily scalable: you can quickly add hockey, basketball, or esports to the football bot without rewriting the architecture.

How to choose and connect a sports events API: registration, keys, limits

Before launching the bot, it is important to properly choose a sports API provider and correctly configure the connection. First of all, evaluate which tournaments and sports you need, and whether the API has the specific leagues for which notifications are planned. Next, pay attention to the availability of detailed events: not every service has separate types for goals, cards, or substitutions, as well as detailed statistics on corners. api-sport.ru All this data is available through the openly described OpenAPI specification, so the developer understands the structure of the responses in advance and can accurately plan the bot’s logic. Additionally, consider the availability of data on bookmaker coefficients if integration with betting is planned.

Connecting to the API comes down to obtaining an individual key and adding it to each request. On the platform api-sport.ru, this is done through your personal account: after registration, you receive an API key and specify it in the header Authorization. Then any HTTP client (curl, axios, fetch, requests, etc.) will be able to access the API methods. The simplest example in JavaScript might look like this:

fetch('https://api.api-sport.ru/v2/football/matches?status=inprogress', {
  headers: { 'Authorization': 'YOUR_API_KEY' }
})
  .then(res => res.json())
  .then(data => console.log(data.matches));

Study the limitations on request frequency and sample size separately. Any sports API has basic limits on the number of requests per unit of time, and a bot with frequent polling must work correctly with them. Usually, a reasonable polling interval (for example, 5-10 seconds for key matches) and caching data where high frequency is not critical is sufficient. As the load increases, you can optimize the logic: use filters by match status, tournaments, or teams, request only the truly necessary fields, and in the future, switch to WebSocket, which is planned to be launched on api-sport.ru and will allow receiving event updates without constant REST polling.

How to get data on goals, corners, and cards via API: request and response structure

For the bot to correctly respond to goals, corners, and cards, it is necessary to understand where exactly in the API responses this data is located. In the football section, /v2/football/ the main sources are the methods /matches, /matches/{matchId} и /matches/{matchId}/events. In the match object, the field liveEvents contains an array of real-time events. Each element is described by a type (type: goal, card, etc.), the time of the event in minutes (время), the team (команда: home/away) and, if available, the player. Based on these fields, it is easy to determine what exactly happened and what notification text needs to be generated for the user.

Corners and cards are conveniently read from the block matchStatistics, which comes along with the match. It contains an array of periods (for example, ALL, 1ST, 2ND), within which there are groups of statistics and elements with keys such as угловые удары or yellowCards. This allows the bot to track cumulative metrics: for example, to send a signal as soon as the team takes the fifth corner or receives the third yellow card. Below is a simplified fragment of the JSON response to illustrate the structure:

{
«id»: 14570728,
«homeScore»: { «current»: 1 },
«awayScore»: { «current»: 0 },
«liveEvents»: [
{
«time»: 23,
«type»: «goal»,
«team»: «home»,
«homeScore»: 1,
«awayScore»: 0
},
{
«time»: 30,
«type»: «card»,
«team»: «away»,
«reason»: «Yellow card»
}
],
«matchStatistics»: [
{
«period»: «ALL»,
«groups»: [
{
«groupName»: «Match overview»,
«statisticsItems»: [
{ «key»: «cornerKicks», «homeValue»: 4, «awayValue»: 2 },
{ «key»: «yellowCards», «homeValue»: 1, «awayValue»: 2 }
]
}
]
}
]
}

On the bot’s side, it is enough to remember the previous state of the match statistics and compare it with the new API response. If the indicator for corners or cards has increased, or a new element has appeared in the array liveEvents of type goal, A notification is formed and sent. This approach works equally well for simple alerts like «Goal! 1:0» and for more complex triggers related to betting and live analytics, especially considering that the API api-sport.ru additionally provides the basic odds from bookmakers through the field oddsBase.

How to create a Telegram bot with notifications about goals and cards based on a sports API

The practical scheme of the Telegram bot works like this: the user launches the bot, selects the tournaments or teams of interest, the bot saves these settings and then periodically queries the sports API to check for new events. When a goal or card appears, the bot sends a message to the user in Telegram. It is convenient to use the REST API https://api.api-sport.ru/v2/football with filtering by match status (inprogress) and the required tournaments or teams. Thus, the main logic is transferred to a single background loop that polls the API and updates the state of the tracked matches.

Below is an example of simplified Python code that illustrates the basic idea: a request to the sports events API and sending a notification via the Telegram Bot API. For brevity, error handling and state storage are not shown here, but the principle remains the same in any production implementations:

import requests
API_KEY = 'YOUR_API_KEY'
TELEGRAM_TOKEN = 'TELEGRAM_BOT_TOKEN'
CHAT_ID = 'USER_CHAT_ID'
base_url = 'https://api.api-sport.ru/v2/football/matches'
resp = requests.get(base_url, params={
    'status': 'inprogress'
}, headers={'Authorization': API_KEY})
matches = resp.json().get('matches', [])
for match in matches:
    for event in match.get('liveEvents', []):
        if event['type'] == 'goal':
            text = f"Гол! Счет {event['homeScore']}:{event['awayScore']} на {event['time']} минуте"
            requests.get(f"https://api.telegram.org/bot{TELEGRAM_TOKEN}/sendMessage", params={
                'chat_id': CHAT_ID,
                'text': text
            })

In practice, the bot should save the IDs of already processed events to avoid sending duplicate notifications and maintain user settings: which matches to track, which types of events are of interest. All this is implemented on your server or cloud function side, while the sports events API from api-sport.ru provides a stable and predictable data source. As the service evolves, there will be an opportunity to use WebSocket connections and AI functions for predictive analytics, making such bots even faster and more accurate without complicating the logic on your side.

Setting up filters and notification frequency for the football match bot

To prevent the bot from overwhelming the user while also not missing important events, it is necessary to properly configure the filters and polling frequency of the API. In requests to /v2/football/matches it is advisable to use parameters status=inprogress, tournament_id, team_id и category_ids. This way, the bot will receive only those games that are actually happening at the moment and are genuinely interesting to the user audience. For example, to track only the Champions League and the English Premier League, it is enough to pass their IDs separated by commas in the parameter tournament_id, and for personalization — limit to matches of a specific team through team_id.

API polling can be organized by timer or through a scheduler task. The interval depends on the project’s requirements for response speed. For most bots, 5–15 seconds is sufficient, especially if only key matches are processed. At the same time, it is important not to forget about limits: with a large number of users and tournaments, it is better to separate the logic into several threads and cache data where a small delay is acceptable (for example, corner statistics every 30 seconds). To increase accuracy, two levels can be combined: frequent polling of a limited list of «hot» matches and less frequent updates of the general list of meetings.

Filters at the business logic level allow for flexible management of load and UX. The user can choose which events interest them: only goals, goals and cards, all key statistical changes. The bot saves these settings and, upon receiving an API response, compares it with the user’s profile. For example, if only corners are enabled, the bot analyzes the block matchStatistics and sends a notification only when the specified threshold is reached. This approach makes working with the API efficient: a minimal number of requests, maximum useful notifications, and high audience loyalty to your product.

Typical mistakes and limitations when working with sports events APIs and how to overcome them

When developing a bot based on a sports API, the same mistakes often occur. The most common one is incorrect authorization: missing header Authorization or using an expired key. As a result, the server returns status 401, and the bot «remains silent.» This problem is solved by a simple configuration check at the application startup and centralized storage of the key obtained through your personal account. The second common mistake is incorrect use of filtering parameters: incorrect sportSlug (for example, a typo instead of football), incorrect tournament or team IDs. In such cases, it is important to log requests and responses to quickly see the sources of problems.

Another typical scenario is exceeding request limits. If the bot tries to poll the API too frequently or without filters, it leads to errors and delays. To avoid this, build caching, request aggregation, and reasonable polling intervals into the architecture. For example, instead of requesting details separately for each match every second, you can get the list of matches once through /v2/football/matches?status=inprogress, and then update only the truly important games on a case-by-case basis. In the future, the transition to WebSocket, which is planned on the api-sport.ru platform, will allow for the complete elimination of «unnecessary» polling and receiving events via subscription.

Another important aspect is the correct handling of the response structure. Sometimes developers rigidly tie themselves to the order of elements in the array or do not handle new fields that appear as the API evolves. The correct strategy is to focus on the keys described in the OpenAPI specification (for example, type, время, matchStatistics, oddsBase), and to anticipate that additional data may appear in the response. This makes the bot resilient to platform updates and allows for the seamless integration of new features, such as statistics for other sports, integration with betting odds APIs, or AI services based on data. api-sport.ru.