Football API Tutorials

Getting Started with FootyStats API

This tutorial will show you all you need to know in order to get your API account up and running. We'll end with you making your very first API call. Ready? Let's get started.

Watch Video Tutorial

5 Easy Steps

We will break this tutorial down into four sections:

  • Create Your Account
  • Subscribe for API Access
  • Select Your Leagues
  • Start Making API Calls

1: Creating Your Account

Creating a new account with FootyStats is easy, and takes no longer than a minute. If you already have an account with FootyStats, you can use the same details to log into the API platform.

Create Account

2: Subscribe to FootyStats

Access to the API requires a subscription, with packages starting at £29.99 per month. You can test the API response by using the &key=example parameter. This works for all API calls listed in the documentation.

League Tables
All example API calls will be limited to showing data from the English Premier League 2018/2019 season.

3: Selecting Your Leagues

Depending on your package, you will have a limited number of leagues. Adding new leagues is easy, simply head to your account page and scroll towards the bottom of the page where you will see a list of countries and leagues. Check the ones you would like included in your package. You may have to wait ~5 minutes for the changes to take effect across all of our platforms. You're able to add a few leagues at first whilst you test your project, then come back later and complete your package.

View Included Leagues

4: Making API Calls

No matter what platform or progamming language you're using to create your product, returning our data in JSON is incredibly easy. Here's how you find the matches that were played in the 2018/2019 La Liga season.

API Call
	id: 453873,
	homeID: 149,
	awayID: 108,
	season: "2018/2019",
	status: "complete",
	roundID: 3547,
	game_week: 1,
	revised_game_week: -1,
	homeGoals: [],
	awayGoals: [],
	homeGoalCount: 2,
	awayGoalCount: 1,
	totalGoalCount: 3,
	team_a_corners: 2,
	team_b_corners: 7,
{} // Match Object
{} // Match Object

Retrieving All Premier League Matches from 2018/2019

In this tutorial, we will show you how easy it is to attain all of the matches from any given season. In this example, we'll use the English Premier League stats and matches from 2018/2019, where Manchester City claimed their 2nd sucessive Premier League title.

1: Establishing Your Connection

First, check that your API key is active and working. Hitting this URL, whilst adding your API key, should return a response of true. If you have not got your API key yet, please visit your account page.

Basic API Call

2: Finding Matches Using The League ID

View method for exploring all data-points and IDs via our documentation page. For this tutorial, we will be listing all of the matches from the latest EPL season in a project that you will be able to download at the end of this tutorial.

API Call for League Matches

In this case, the ID for the latest EPL season is 1625 and we can access the matches from this season by using the league-matches API call. Your JSON response will contain 380 games, all packed with stats ready for saving or manipulating. Pagination is available by adding &page=PAGE_NUMBER to the end of your API call.

Example Match Object
   homeGoals:[  ],
   awayGoals:[  ],

3: Working With The Data

Once you have the response back from the server, you can manipulate the date to fit your needs. In this example, we will be looping through the games and displaying the matches in a table. To view all of the data-points available in each match object that's returned, please view our documentation.

For this tutorial, we'll be working in PHP. JSON can be manipulated by most programming languages. For more on working with JSON, we recommend these articles:

4: Saving Data to Variable

We have created league-matches.php and inside this file we are going to utilise the file_get_contents() function. This PHP function is used to read a file and convert into a string. Once we have that string, we will need to use json_decode() to convert our string into an array that we can utilise and manipulate.

$result = file_get_contents("");

$result = json_decode($result, true);

$matches = $result['data'];

Using var_dump() on your new $matches variable will show you all of the matches for this league. However, that's no use to anyone. In the next steps, we will loop through and manipulate the data.

5: Looping Through Matches

We'll start by creating a simple foreach loop for $matches that displays both team names.

foreach($matches as $match):
	echo "{$match['home_name']} vs {$match['away_name']}";
HTML Output
Manchester United vs Leicester City 
Newcastle United vs Tottenham Hotspur 
AFC Bournemouth vs Cardiff City 

6: Adding More Data-Points to Your HTML

Now we have a working list of matches, we're free to manipulate it as we see fit. Now, what's the point of showing results without the scores? Let's add to our existing code.

foreach($matches as $match){
	echo $match['home_name'];
	echo $match['homeGoalCount'];
	echo $match['awayGoalCount'];
	echo $match['away_name'];
	echo "<br>"
HTML Output
Manchester United 2-1 Leicester City 
Newcastle United 1-2 Tottenham Hotspur 
AFC Bournemouth 2-0 Cardiff City 

7: Filtering Matches

Now, let's add a condition to our $matches loop to show only games that contained 3 goals or more.

if($match['totalGoalCount'] >= 3){
	echo $match['home_name'];
	echo $match['homeGoalCount'];
	echo $match['awayGoalCount'];
	echo $match['away_name'];
	echo "<br>"
} else {
	// Do Something Else
HTML Output
Manchester United 2-1 Leicester City
Newcastle United 1-2 Tottenham Hotspur
Huddersfield Town 0-3 Chelsea

Thanks for Reading

If you're planning on building an application with this data, why not have filters for $match['date_unix'] and allow the user to view games by the week, or month. The possibilities are endless. We hope you found this tutorial easy to understand and are now able to create your own applications using the FootyStats API. You can download the league-matches.php file using the button in the sidebar to start testing on your computer.

Displaying League Tables

This tutorial will show you how to display league tables from any of the leagues that you have selected in your API package. We'll be using the &key=example API call so you can follow along without subscribing. We will be displaying the table for the 2018/2019 English Premier League.

Watch Video Tutorial

1: The API Call

Example API Call

Throughout these tutorials, when we use the &key=example, it will automatically show you the data for the English Premier League 2018/2019 season. This is true for all API calls and no league parameters are needed.

2: The JSON Response

In this case, we'll be returned an array of teams, ranked in order of league standing.

Manchester City
	id: 93,
	seasonGoals_home: 57,
	seasonGoals_away: 38,
	seasonConceded_away: 11,
	seasonConceded_home: 12,
	seasonGoals: 95,
	points: 98,
	ppg_overall: 2.5789473684210527,
	seasonGoalDifference: 72,
	seasonWins_home: 18,
	seasonWins_away: 14,
	seasonDraws_home: 0,
	seasonDraws_away: 2,
	seasonLosses_away: 3,
	seasonLosses_home: 1,
	matchesPlayed: 38,
	name: "Manchester City FC",
	country: "england",
	cleanName: "Manchester City",
	shortHand: "manchester-city-fc",
	url: "/clubs/england/manchester-city-fc",
	seasonURL_overall: "/clubs/england/manchester-city-fc",
	seasonURL_home: "/clubs/england/manchester-city-fc",
	seasonURL_away: "/clubs/england/manchester-city-fc",
	position: 1,
		zone: {
		name: "UEFA Champions League",
		number: 1

3: Convert The Data (JSON)

First, let's convert the JSON into something we can work with in PHP.

$url = "API_CALL";
$result = file_get_contents($url);
$result = json_decode($result, true);

4: Selecting Table Data

For every league, we offer the following tables:

JSON Response
data: {
	league_table: [],
	specific_tables: [],
	all_matches_table_overall: [],
	all_matches_table_home: [],
	all_matches_table_away: []

Each of these arrays contains team objects, just like the Manchester City one we mentioned above. For this example, we're going to loop through and create a table that shows the best away teams in the Premier League.

Select the data you require like this:

$teams = $result['data']['all_matches_table_away'];

5: Looping Through Teams

Next, we loop through the teams whilst calling the stats we need.

foreach($teams as $team):
	echo "{$team['position']}:";
	echo "{$team['name']},";
	echo "{$team['matchesPlayed']}";
	echo "{$team['seasonWins']}";
	echo "{$team['seasonDraws']}";
	echo "{$team['seasonLosses_away']}";
	echo "{$team['points']}";
HTML Output
1: Manchester City - 19, 14, 2, 3, 44
2: Liverpool - 19, 13, 5, 1, 44
3: Tottenham - 19, 11, 0, 8, 33
HTML output has been simplified for the ease of reading this tutorial. Please download the example files, where a full <table> is created.

Thanks for Reading

If you're planning on building an application with this data, why not create your own tables by filtering through the teams to meet your specific needs. The possibilities are endless. We hope you found this tutorial easy to understand and are now able to create your own applications using the FootyStats API. You can download the league-tables.php file using the button in the sidebar to start testing on your computer.

Creating Basic Betting Strategy

This tutorial will show you how to build a basic betting strategy using the FootyStats API. We will look for certain indicators and trends in returned fixtures.

1: Introduction

In this tutorial, we will presume that you have read through our previous tutorials and know how to get the requried match objects using the API. You can use any matches you like, as it's the rules and parameters that we'll be focusing on here. At the end of this tutorial, we will have a function that shows us only the matches that fit our specifications. Got your list of matches? Let's get started.

2: BTTS Games

I have a huge list of upcoming matches from 10 of my favourite leagues. For the first example, I want to show the following:

  • Games with BTTS Rank of 65%+
  • Away Team has 1.50+ PPG Away from Home

So, let's create the rules for this:

$myBTTSGames = array();
foreach($games as $game):
	if($game['away_ppg'] >= 1.50 && $game['btts_potential'] >= 65):
		$myBTTSGames[] = $game;

Here we have created a new array here that will contain our selected BTTS games. Following the same pattern, let's find games with a low chance of goals.

3: Low-Scoring Games

In this example, we will filter through our array of games for the following:

  • AVG Goals: 1.80 Or Less
  • PPG: 1.50 or Less (For Both Teams)
$lowScoringGames = array();
foreach($games as $game):
	if($game['avg_potential'] <= 1.80 && $game['home_ppg'] <= 1.50 && $game['away_ppg'] <= 1.50):
		$lowScoringGames[] = $game;

4: Printing Results

foreach($lowScoringGames as $game):

This will loop through all of the games in your array and run a function called createTable. It might be that this function adds each of these games to an existing table in your database. Check out the examples files, where we set these rules up and have a table generated that shows only the games that meet these rules.