With this endpoint you can pit any two teams head to head. Just supply both ::team_id:: values and the service returns the comparison for you.
If you are building anything football related, a website, a mobile app or even a TV show, users will expect to compare two teams. Not only against each other but also across other indicators. That is exactly why the head to head comparison endpoint exists. Plug it in and you can hand your users precisely that information without building the logic yourself. Any football api would feel incomplete without it.
Endpoint
Working with the football api head to head endpoint is straightforward. The only required input is the ids of the two teams you want to compare. If you also want team names translated into a language other than English, pass the ISO 2 letter code for that language. Every football api endpoint that returns team information also includes the id of the team, so you can chain calls without extra lookups. There is also a dedicated endpoint for listing all teams or filtering them by specific criteria. More on that in our teams api endpoint page. For everything related to language handling, head over to our language support documentation page. You can pull head 2 head information from the following api endpoint.
Check this Football API endpoint in our postman collection. Download it now!
In the example above we are putting two rivals side by side: Tottenham Hotspur and Manchester United. The response from our football API comes back as an extensive list of matches plus additional information you can use right away. An example response is show below, and right after it you will find an explanation of what each piece of data contains. But before we get there, let us walk through the parameters you need to pass to the football api endpoint so it can do its thing.
Parameters
| Name | Type | Required | Example | Description |
|---|---|---|---|---|
| lang | string | ar | The language code that tells the football api which language you want the returned data in. | |
| team1_id | number | 1 | 7 | The id of the first team in the comparison. |
| team2_id | number | 1 | 19 | The id of the second team in the comparison. |
Response
The data coming back from our football api head to head endpoint is fairly long, as the example below shows. If you would rather skip ahead, jump straight to the explanation that follows 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
}
}
}
}That is quite a bit of data to take in. Let us split it into sections and go through what each one holds. The table below covers the major pieces of data, and a more detailed breakdown of what lives inside each section follows right after it.
| Name | Type | Example | Description |
|---|---|---|---|
| fixture | object | The next fixture in which the two teams will face each other. | |
| h2h | object | Holds the data for the previous meetings between the two teams. | |
| team1 | object | Holds the general information about the first team. | |
| team1_last_6 | object | Carries the data for the last 6 games played by the first team. | |
| team2 | object | Holds the general information about the second team. | |
| team2_last_6 | object | Carries the data for the last 6 games played by the second team. |
team1 and team2
The first two sections of the response, team1 and team2, follow the same structure. They carry general information about each team such as
id the id of the team
name the name of the team
country the id of the country the team belongs to
stadium the ground where the team plays its home matches
After that general block comes the current form of the team, plus its form against the other side:
overall_form the overall form of the team across its last 6 games
h2h_form the overall form of the team against the other team
Inside both form lists you will run into the letters W, D and L. They stand for a won game, a drawn game and a lost game respectively.
team1_last_6 and team2_last_6
These two sections list the last 6 matches for each team, pulled from our historical data. If a match is still live in the livescore feed, it will not show up here. More on that in our livescore api endpoint. The matches listed are games the teams played against any opponent across all competitions. Now and then one of them will be against the team you are comparing with, but that is rare. In this historical match data you will find every field we already covered in our football history api endpoint. Here is a quick recap:
id the match id
date when the match was played, in UTC
home_name the name of the home team
away_name the name of the away team
ht_score the half time score
ft_score the full time score
et_score the score after extra time, if it was played
league_id the id of the league the match belonged to. Keep in mind leagues are deprecated and all new endpoints support competitions only
home_id the id of the home side
away_id the id of the away side
competition_id the id of the competiiton the game was part of
location where the match was held
scheduled the scheduled kick off time, in UTC
league additional information about the league
competition additional information about the competition
outcomes the betting outcomes for each half and for extra time. The familiar 1, X and 2 stand for home team winning, draw and away team winning respectively.
h2h
Inside the h2h section you will find the most recent meetings between the two sides. This also comes from our history database, so any match currently in the livescore feed will not appear here. The fields match the ones from the previous two sections, team1_last_6 and team2_last_6.
Fixture
This key holds information about the next match the two teams will play against each other in any competition. The fixture object follows the same structure as the fixtures returned by the fixtures football api endpoint.