Head 2 Head
Using this API endpoint you can compare 2 teams against each other.
For any football-related product, whether it is a website, mobile app or TV show, it is of uttermost importance for the users to be able to compare 2 teams. That is, against each other as well as in other indicators. That is why we added the head to head comparison endpoint. Using it, you would be able to provide your users with just this information. Any football api would be incomplete without this endpoint.
Endpoint
When using our football api head to head endpoint all you need is the team IDs of the 2 teams that you are comparing. In case you need to translate the team names in a language different from English, you need the ISO 2 letter code of the language. Every football api endpoint that has team information in its results has the team ID as well. We also have an API endpoint that you can use to list all teams or filter them by certain criteria. You can read more about this on our special teams api endpoint page. If you would like to know more about our language support, you can find everything you need at our language support documentation page. You can get the head 2 head information using the following api endpoint:
In the example above, we are comparing 2 of the biggest rivals in the world: Liverpool and Manchester United. The response of our football API is an extensive list of matches and additional information that you can use straight away. We have listed the example response below, and after it, there is an explanation of what the data contains. But first, let's look at the parameters that you need to provide to the football api endpoint, in order for it to do its magic.
Parameters
| Name | Type | Required | Example | Description |
|---|---|---|---|---|
| lang | string | ar | The language code of the language in which we want the data in. | |
| team1_id | number | 1 | 7 | The ID of the first team that we are comparing. |
| team2_id | number | 1 | 19 | The ID of the second team that we are comparing. |
Response
This response from our football api head to head endpoint is pretty long. As you can see from the example below. If you want to skip it, you can scroll directly to the explanation following it using this link
{
"success": true,
"data": {
"team1": {
"id": "15",
"name": "Tottenham Hotspur",
"stadium": "Tottenham Hotspur Stadium",
"location": "Tottenham Hotspur Stadium",
"overall_form": [
"W",
"L",
"L",
"W",
"W",
"W"
],
"h2h_form": [
"W",
"D",
"L",
"L",
"L",
"W"
]
},
"team2": {
"id": "19",
"name": "Manchester United",
"stadium": "Old Trafford",
"location": "Old Trafford",
"overall_form": [
"L",
"W",
"W",
"D",
"W",
"D"
],
"h2h_form": [
"L",
"D",
"W",
"W",
"W",
"L"
]
},
"team1_last_6": [
{
"id": "242125",
"date": "2021-03-21",
"home_name": "Aston Villa",
"away_name": "Tottenham Hotspur",
"score": "0 - 2",
"ht_score": "0 - 1",
"ft_score": "0 - 2",
"et_score": "",
"league_id": "0",
"home_id": "495",
"away_id": "15",
"competition_id": "2",
"location": "Villa Park",
"scheduled": "19:30",
"league": [],
"competition": {
"id": "2",
"name": "Premier League"
},
"outcomes": {
"half_time": "2",
"full_time": "2",
"extra_time": null
}
},
{
"id": "241149",
"date": "2021-03-18",
"home_name": "Dinamo Zagreb",
"away_name": "Tottenham Hotspur",
"score": "3 - 0",
"ht_score": "0 - 0",
"ft_score": "2 - 0",
"et_score": "3 - 0",
"league_id": "0",
"home_id": "905",
"away_id": "15",
"competition_id": "245",
"location": "Stadion Maksimir",
"scheduled": "17:55",
"league": [],
"competition": {
"id": "245",
"name": "Europa League"
},
"outcomes": {
"half_time": "X",
"full_time": "1",
"extra_time": "1"
}
},
{
"id": "240510",
"date": "2021-03-14",
"home_name": "Arsenal",
"away_name": "Tottenham Hotspur",
"score": "2 - 1",
"ht_score": "1 - 1",
"ft_score": "2 - 1",
"et_score": "",
"league_id": "0",
"home_id": "18",
"away_id": "15",
"competition_id": "2",
"location": "Emirates Stadium",
"scheduled": "16:30",
"league": [],
"competition": {
"id": "2",
"name": "Premier League"
},
"outcomes": {
"half_time": "X",
"full_time": "1",
"extra_time": null
}
},
{
"id": "239490",
"date": "2021-03-11",
"home_name": "Tottenham Hotspur",
"away_name": "Dinamo Zagreb",
"score": "2 - 0",
"ht_score": "1 - 0",
"ft_score": "2 - 0",
"et_score": "",
"league_id": "0",
"home_id": "15",
"away_id": "905",
"competition_id": "245",
"location": "Tottenham Hotspur Stadium",
"scheduled": "20:00",
"league": [],
"competition": {
"id": "245",
"name": "Europa League"
},
"outcomes": {
"half_time": "1",
"full_time": "1",
"extra_time": null
}
},
{
"id": "238882",
"date": "2021-03-07",
"home_name": "Tottenham Hotspur",
"away_name": "Crystal Palace",
"score": "4 - 1",
"ht_score": "1 - 1",
"ft_score": "4 - 1",
"et_score": "",
"league_id": "25",
"home_id": "15",
"away_id": "3",
"competition_id": "2",
"location": "Tottenham Hotspur Stadium",
"scheduled": "19:15",
"league": {
"id": "25",
"name": "Premier League",
"country_id": "19"
},
"competition": {
"id": "2",
"name": "Premier League"
},
"outcomes": {
"half_time": "X",
"full_time": "1",
"extra_time": null
}
},
{
"id": "237865",
"date": "2021-03-04",
"home_name": "Fulham",
"away_name": "Tottenham Hotspur",
"score": "0 - 1",
"ht_score": "0 - 1",
"ft_score": "0 - 1",
"et_score": "",
"league_id": "25",
"home_id": "502",
"away_id": "15",
"competition_id": "2",
"location": "Craven Cottage ",
"scheduled": "18:00",
"league": {
"id": "25",
"name": "Premier League",
"country_id": "19"
},
"competition": {
"id": "2",
"name": "Premier League"
},
"outcomes": {
"half_time": "2",
"full_time": "2",
"extra_time": null
}
}
],
"team2_last_6": [
{
"id": "242084",
"date": "2021-03-21",
"home_name": "Leicester City",
"away_name": "Manchester United",
"score": "3 - 1",
"ht_score": "1 - 1",
"ft_score": "3 - 1",
"et_score": "",
"league_id": "0",
"home_id": "6",
"away_id": "19",
"competition_id": "152",
"location": "King Power Stadium",
"scheduled": "17:00",
"league": [],
"competition": {
"id": "152",
"name": "FA Cup"
},
"outcomes": {
"half_time": "X",
"full_time": "1",
"extra_time": null
}
},
{
"id": "241156",
"date": "2021-03-18",
"home_name": "AC Milan",
"away_name": "Manchester United",
"score": "0 - 1",
"ht_score": "0 - 0",
"ft_score": "0 - 1",
"et_score": "",
"league_id": "0",
"home_id": "85",
"away_id": "19",
"competition_id": "245",
"location": "Stadio Giuseppe Meazza",
"scheduled": "20:00",
"league": [],
"competition": {
"id": "245",
"name": "Europa League"
},
"outcomes": {
"half_time": "X",
"full_time": "2",
"extra_time": null
}
},
{
"id": "240559",
"date": "2021-03-14",
"home_name": "Manchester United",
"away_name": "West Ham United",
"score": "1 - 0",
"ht_score": "0 - 0",
"ft_score": "1 - 0",
"et_score": "",
"league_id": "0",
"home_id": "19",
"away_id": "14",
"competition_id": "2",
"location": "Old Trafford",
"scheduled": "19:15",
"league": [],
"competition": {
"id": "2",
"name": "Premier League"
},
"outcomes": {
"half_time": "X",
"full_time": "1",
"extra_time": null
}
},
{
"id": "239479",
"date": "2021-03-11",
"home_name": "Manchester United",
"away_name": "AC Milan",
"score": "1 - 1",
"ht_score": "0 - 0",
"ft_score": "1 - 1",
"et_score": "",
"league_id": "0",
"home_id": "19",
"away_id": "85",
"competition_id": "245",
"location": "Old Trafford",
"scheduled": "17:55",
"league": [],
"competition": {
"id": "245",
"name": "Europa League"
},
"outcomes": {
"half_time": "X",
"full_time": "X",
"extra_time": null
}
},
{
"id": "238819",
"date": "2021-03-07",
"home_name": "Manchester City",
"away_name": "Manchester United",
"score": "0 - 2",
"ht_score": "0 - 1",
"ft_score": "0 - 2",
"et_score": "",
"league_id": "25",
"home_id": "12",
"away_id": "19",
"competition_id": "2",
"location": "Etihad Stadium",
"scheduled": "16:30",
"league": {
"id": "25",
"name": "Premier League",
"country_id": "19"
},
"competition": {
"id": "2",
"name": "Premier League"
},
"outcomes": {
"half_time": "2",
"full_time": "2",
"extra_time": null
}
},
{
"id": "237770",
"date": "2021-03-04",
"home_name": "Crystal Palace",
"away_name": "Manchester United",
"score": "0 - 0",
"ht_score": "0 - 0",
"ft_score": "0 - 0",
"et_score": "",
"league_id": "0",
"home_id": "3",
"away_id": "19",
"competition_id": "2",
"location": "Selhurst Park",
"scheduled": "20:15",
"league": [],
"competition": {
"id": "2",
"name": "Premier League"
},
"outcomes": {
"half_time": "X",
"full_time": "X",
"extra_time": null
}
}
],
"h2h": [
{
"id": "213433",
"date": "2020-10-04",
"home_name": "Manchester United",
"away_name": "Tottenham Hotspur",
"score": "1 - 6",
"ht_score": "1 - 4",
"ft_score": "1 - 6",
"et_score": "",
"league_id": "25",
"home_id": "19",
"away_id": "15",
"competition_id": "2",
"location": "Old Trafford",
"scheduled": "15:30",
"outcomes": {
"half_time": "2",
"full_time": "2",
"extra_time": null
},
"competition": {
"id": "2",
"name": "Premier League"
},
"league": {
"id": "25",
"name": "Premier League",
"country_id": "19"
}
},
{
"id": "197918",
"date": "2020-06-19",
"home_name": "Tottenham Hotspur",
"away_name": "Manchester United",
"score": "1 - 1",
"ht_score": "1 - 0",
"ft_score": "1 - 1",
"et_score": "",
"league_id": "25",
"home_id": "15",
"away_id": "19",
"competition_id": "2",
"location": "Tottenham Hotspur Stadium",
"scheduled": "19:15",
"outcomes": {
"half_time": "1",
"full_time": "X",
"extra_time": null
},
"competition": {
"id": "2",
"name": "Premier League"
},
"league": {
"id": "25",
"name": "Premier League",
"country_id": "19"
}
},
{
"id": "175650",
"date": "2019-12-04",
"home_name": "Manchester United",
"away_name": "Tottenham Hotspur",
"score": "2 - 1",
"ht_score": "1 - 1",
"ft_score": "2 - 1",
"et_score": "",
"league_id": "25",
"home_id": "19",
"away_id": "15",
"competition_id": "2",
"location": "Old Trafford",
"scheduled": "19:30",
"outcomes": {
"half_time": "X",
"full_time": "1",
"extra_time": null
},
"competition": {
"id": "2",
"name": "Premier League"
},
"league": {
"id": "25",
"name": "Premier League",
"country_id": "19"
}
},
{
"id": "150342",
"date": "2019-07-25",
"home_name": "Tottenham Hotspur",
"away_name": "Manchester United",
"score": "1 - 2",
"ht_score": "0 - 1",
"ft_score": "1 - 2",
"et_score": "",
"league_id": "806",
"home_id": "15",
"away_id": "19",
"competition_id": "369",
"location": "Tottenham Hotspur Stadium",
"scheduled": "11:30",
"outcomes": {
"half_time": "2",
"full_time": "2",
"extra_time": null
},
"competition": {
"id": "369",
"name": "Champions Cup"
},
"league": {
"id": "806",
"name": "Champions Cup:: play-off",
"country_id": "4"
}
},
{
"id": "123072",
"date": "2019-01-13",
"home_name": "Tottenham Hotspur",
"away_name": "Manchester United",
"score": "0 - 1",
"ht_score": "0 - 1",
"ft_score": "0 - 1",
"et_score": "",
"league_id": "25",
"home_id": "15",
"away_id": "19",
"competition_id": "2",
"location": null,
"scheduled": null,
"outcomes": {
"half_time": "2",
"full_time": "2",
"extra_time": null
},
"competition": {
"id": "2",
"name": "Premier League"
},
"league": {
"id": "25",
"name": "Premier League",
"country_id": "19"
}
},
{
"id": "102984",
"date": "2018-08-27",
"home_name": "Manchester United",
"away_name": "Tottenham Hotspur",
"score": "0 - 3",
"ht_score": "0 - 0",
"ft_score": "0 - 3",
"et_score": "",
"league_id": "25",
"home_id": "19",
"away_id": "15",
"competition_id": "2",
"location": null,
"scheduled": null,
"outcomes": {
"half_time": "X",
"full_time": "2",
"extra_time": null
},
"competition": {
"id": "2",
"name": "Premier League"
},
"league": {
"id": "25",
"name": "Premier League",
"country_id": "19"
}
}
],
"fixture": {
"id": "1367020",
"date": "2021-04-11",
"time": "15:30:00",
"round": "31",
"home_name": "Tottenham Hotspur",
"away_name": "Manchester United",
"location": "Tottenham Hotspur Stadium",
"league_id": "25",
"home_id": "15",
"away_id": "19",
"competition_id": "2",
"competition": {
"id": "2",
"name": "Premier League"
},
"league": {
"id": 25,
"name": "Premier League",
"country_id": 19
}
}
}
}This is a significant chunk of information. Let's break it down in sections and see what they contain. The table below explains the big pieces of data. The table is followed by a detailed explanation of the information inside each section.
| Name | Type | Example | Description |
|---|---|---|---|
| fixture | object | The next match that the teams will be playing agains each other. | |
| h2h | object | Contains that data of the last matches between the 2 teams | |
| team1 | object | Contains the overall information about the first team. | |
| team1_last_6 | object | Contains the data of the last 6 games of the first team. | |
| team2 | object | Contains the overall information about the second team. | |
| team2_last_6 | object | Contains the data of the last 6 games of the second team. |
team1 and team2
The first 2 sections of the response team1 and team2 are identical. They include general information about the teams like
* id - the id of the team
* name - the name of the team
* country - the id of the country from where the team is
* stadium - the stadium where the team plays its home matches
Following this general information is the information about the current form of the team as well as the form of the team against the other team:
* overall_form - the overall form of the team in the last 6 games
* h2h_form - the overall form of the team against the other team
In both form lists, you will find the letters: W, D, L. These letters signify respectively: a won game, a drawn game, and a lost game.
team1_last_6 and team2_last_6
In these 2 sections, you will find a list of the last 6 matches of the teams. This information comes from our historical data. If there is a match still in the livescore score feed you won't see the match here. You can read more about about our livescore api endpoint here. In this section, are matches that the teams played against other teams in all competitions. Occasionally, it might happen that they played with the team you are comparing it with, but it will be very rare. In this historical matches data, you will find all the fields that we have explained in our football history api endpoint. Here we briefly mention them one more time:
* id - the id of the match
* date - the date when the match was played, the data is in the UTC timezone
* home_name - the name of the home team
* away_name - the name of the away team
* ht_score - score at half time
* ft_score - score at full time
* et_score - score after the extra time has finished, if there was any
* league_id - the id of the league in which the match was played. Be mindful that leagues are deprecated and all new endpoints will support only competitions
* home_id - the id of the home team
* away_id - the id of the away team
* competition_id the id of the competition in which the game was part of
* location - the place where the match was held
* scheduled - at what time the match was scheduled to start. This time is in the UTC timezone
* league - additional information about the league
* competition - additional information about the competition
* outcomes - that would be the betting outcomes for each half of the match as well as the extra time. The well know 1, X, 2, are the signs respectively attributed for: home team winning, draw, away team winning.
h2h
In the h2h section you will find the last matches played between the teams. Again this data is coming from our history database, so if there is a match in the livescore feed it will not appear here. The fields are the same as the ones from the previous 2 sections. team1_last_6 and team2_last_6
Fixture
This key contains information about the next match that the teams are going to play against each other in any competition. The structure of the fixture object is the same as the structure of the fixtures in the fixtures football api endpoint.