Contains all the data regarding the top tier English football division - the Premier League.
From all the players, teams and matches, to live scores and match events, updating by the minute.

Documentation

Models

Player

The Player model represents a player in a Premier League team. Below are the fields associated with the Player model:

Field	Type	Description
name	string	The name of the player.
team	string	Id of the team the player belongs to.
country	string	The country the player is from.
position	string	The position the player plays in.
age	number	The age of the player.
dateOfBirth	date	The date of birth of the player.
height	number	The height of the player.
shirtNumber	number	The shirt number of the player.
goals	number	The number of goals scored by the player.
assists	number	The number of assists made by the player.
appearances	number	The number of appearances made by the player.
firstTeamAppearances	number	The number of first team appearances made by the player.
minutesPlayed	number	The total minutes played by the player.
yellowCards	number	The number of yellow cards the player has received.
redCards	number	The number of red cards the player has received.

Team

The Team model represents a team in the Premier League. Below are the fields associated with the Team model:

Field	Type	Description
name	string	The name of the team.
players	array (string)	A list of ids of the players in the team.
points	number	The total points accumulated by the team.
matchesPlayed	number	The number of matches played by the team.
wins	number	The number of matches won by the team.
draws	number	The number of matches drawn by the team.
losses	number	The number of matches lost by the team.
goalsScored	number	The number of goals scored by the team.
goalsConceded	number	The number of goals conceded by the team.
goalDifference	number	The goal difference of the team.
coach	string	The name of the team's coach.
championships	number	The number of championships won by the team.
runnersUp	number	The number of times the team has been runners-up.

Match

The Match model represents a match in the Premier League. Below are the fields associated with the Match model:

Field	Type	Description
matchWeek	number	The week number of the match.
date	date	The date of the match.
minutesCompleted	number	The number of minutes completed in the match.
isFinished	boolean	Indicates whether the match is finished.
homeTeam	MatchTeam	Information about the home team (model described below).
awayTeam	MatchTeam	Information about the away team (model described below).
winningTeam	string	The name of the winning team (default is 'TBD').
matchEvents	array (GoalEvent | CardEvent | SubstitutionEvent)	The events that occurred during the match (models described below).
stadium	string	The name of the stadium where the match is played.

Match Sub Models

The Match model contains several sub models, all of them are described below:

MatchTeam

Field	Type	Description
team	string	Id of the playing team.
score	number	The score of the team.
lineup	Lineup	The lineup of the team.

Lineup

Field	Type	Description
players	array (LineupPlayer)	A list of players in the lineup (model described below).
formation	string	The formation of the team.

LineupPlayer

Field	Type	Description
player	string	The name of the player.
position	string	The position of the player.
status	'starting' | 'bench'	The status of the player in the lineup.

Common Match Event Properties

Every match event has it's own special properties and consists of the following common fields:

Field	Type	Description
type	'goal' | 'card' | 'substitution'	The type of the match event.
minute	number	The minute the event has occurred.
team	string	The name of the team associated with the event.

GoalEvent

Field	Type	Description
scoringPlayer	string	The name of the player who scored the goal.
assistingPlayer	string	The name of the player who assisted the goal (optional).
subType	'penalty' | 'own goal'	The subtype of the goal (optional).

CardEvent

Field	Type	Description
bookedPlayer	string	The name of the player who received the card.
cardColor	'red' | 'yellow'	The color of the card.

SubstitutionEvent

Field	Type	Description
leavingPlayer	string	The name of the player who left the field.
joiningPlayer	string	The name of the player who joined the field.

Endpoints

Get All Players

Endpoint: GET /players

Description: Retrieves a list of players.

Optional Query Parameterss:

• sort: Sorting criteria, one or more fields optionally fixed by a dash, separated by commas. (For example: goals,-assists)
• limit Limit the number of results.
• Other filter params: name, country, position, age, height, shirtNumber, goals, assists, appearances, firstTeamAppearances, minutesPlayed, yellowCards, redCards.

Get Player By ID

Endpoint: GET /players/:id

Description: Retrieves a player by their ID.

Required Path Parameters:

• id: The ID of the player.

Get Top Scorers

Endpoint: GET /players/topScorers

Description: Retrieves the top 10 players by goals scored.

Get Top Assisters

Endpoint: GET /players/topAssisters

Description: Retrieves the top 10 players by assists made.

Get All Teams

Endpoint: GET /teams

Description: Retrieves a list of teams.

Optional Query Parameterss:

• sort: Sorting criteria, one or more fields optionally fixed by a dash, separated by commas. (For example: championships,-runnersUp)
• limit Limit the number of results.
• Other filter params: name, points, matchesPlayed, wins, draws, losses, goalsScored, goalsConceded, goalDifference, coach, championships, runnersUp.

Get Team By ID

Endpoint: GET /teams/:id

Description: Retrieves a team by its ID.

Required Path Parameters:

• id: The ID of the team.

Get Team Players

Endpoint: GET /teams/:id/players

Description: Retrieves a list of players of a team by its ID.

Required Path Parameters:

• id: The ID of the team.

Get Team Matches

Endpoint: GET /teams/:id/matches

Description: Retrieves a list of matches of a team by its ID.

Required Path Parameters:

• id: The ID of the team.

Get Teams Standings

Endpoint: GET /teams/standings

Description: Retrieves a list of teams sorted by the Premier League rules (points, goal difference, goalsScored).

Get All Matches

Endpoint: GET /matches

Description: Retrieves a list of matches.

Optional Query Parameterss:

• sort: Sorting criteria, one or more fields optionally fixed by a dash, separated by commas. (For example: matchWeek,-stadium)
• limit Limit the number of results.
• Other filter params: matchWeek, minutesCompleted, isFinished, winningTeam, stadium.

Get Match By ID

Endpoint: GET /matches/:id

Description: Retrieves a match by its ID.

Required Path Parameters:

• id: The ID of the match.