International Football Results API

International Football Matches API Documentation

Overview

The International Football Matches API offers a wealth of data related to international men's football. With endpoints that cover matches by year, goals, tournaments, goal scorers, countries, and various statistics, this API provides a comprehensive set of tools for football analysts, enthusiasts, and developers.

Endpoints

1.List of Matches by Year
Method: GET
Endpoint: /matches/by-year
Description: Returns a list of international football matches for a specified year.

Parameters:
year: (integer) The year for which you want the list of matches.

2.Statistics by Team
Method: GET
Endpoint: /statistics/by-team
Description: Returns various statistics about a specific country in international football.

Parameters:
team: (string) The name of the team for which to get the statistics.

3.List of Tournaments
Method: GET
Endpoint: /tournaments
Description: Returns a list of all tournaments for which data is available.
Parameters:

4.List Countries by Tournament
Method: GET
Endpoint: /countries/by-tournament
Description: Returns a list of countries participating in a specific tournament.

Parameters:
tournament: (string, required) The type of tournament for which you want to list the participating countries. This parameter allows you to specify the kind of tournament, such as "FIFA World Cup", "Friendly", "Copa America", etc., and helps retrieve the correct list of countries associated with that specific tournament type.

5.Get Goal Scorers by Specific Match
Method: POST
Endpoint: /goal-scorers/by-match
Description: Returns a list of goal scorers in a specific match.

Parameters:
date: (string, required) The date on which the match took place, in the format YYYY-MM-DD. This parameter specifies the day of the match and helps identify the specific game to retrieve goal information.
awayTeam: (string, required) The name of the away team in the match. This parameter is used to narrow down the match in combination with the date and the home team name.
homeTeam: (string, required) The name of the home team in the match. This parameter, along with the date and away team name, is used to precisely identify the desired match.

6.Get Goals by Match
Method: POST
Endpoint: /goals/by-match
Description: Returns a list of goals scored in a specific match.

Parameters:
date: (string, required) The date on which the match took place, in the format YYYY-MM-DD. This parameter specifies the day of the match and helps identify the specific game to retrieve goal information.
awayTeam: (string, required) The name of the away team in the match. This parameter is used to narrow down the match in combination with the date and the home team name.
homeTeam: (string, required) The name of the home team in the match. This parameter, along with the date and away team name, is used to precisely identify the desired match.

This API includes the following response paramteres:

• date - date of the match
• home_team - the name of the home team
• away_team - the name of the away team
• home_score - full-time home team score including extra time, not including penalty-shootouts
• away_score - full-time away team score including extra time, not including penalty-shootouts
• tournament - the name of the tournament
• city - the name of the city/town/administrative unit where the match was played
• country - the name of the country where the match was played
• neutral - TRUE/FALSE column indicating whether the match was played at a neutral venue
• shootouts.csv includes the following columns:
• winner - winner of the penalty-shootout
• first_shooter - the team that went first in the shootout
• team - name of the team scoring the goal
• scorer - name of the player scoring the goal
• own_goal - whether the goal was an own-goal
• penalty - whether the goal was a penalty

Note on team and country names: For home and away teams the current name of the team has been used. For example, when in 1882 a team who called themselves Ireland played against England, in this dataset, it is called Northern Ireland because the current team of Northern Ireland is the successor of the 1882 Ireland team. This is done so it is easier to track the history and statistics of teams.

For country names, the name of the country at the time of the match is used. So when Ghana played in Accra, Gold Coast in the 1950s, even though the names of the home team and the country don't match, it was a home match for Ghana. This is indicated by the neutral column, which says FALSE for those matches, meaning it was not at a neutral venue.