Teams Head 2 Head

Using this API endpoint you can compare 2 teams against each other.

Although this endpoint supports league data, leagues have been deprecated in favor of the competitions. We advise of using competitions instead of leagues. You can learn more about competitions in their dedicated documentation page.

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, and in case you need that the language code of the language in which you would like to get the results. Any of our 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:


GET:

In the example above we are comparing 2 of the biggest rivals in the world: Liverpool and Manchester United. The response of our 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


NameTypeRequiredExampleDescription
team1_idnumber17The ID of the first team that we are comparing.
team2_idnumber119The ID of the second team that we are comparing.
langstringarThe language code of the language in which we want the data in.

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": "7",
            "name": "Liverpool",
            "stadium": "Anfield",
            "location": "Anfield",
            "overall_form": [
                "W",
                "W",
                "W",
                "W",
                "D"
            ],
            "h2h_form": [
                "D",
                "D",
                "W",
                "W",
                "D",
                "L"
            ]
        },
        "team2": {
            "id": "19",
            "name": "Manchester United",
            "stadium": "Old Trafford",
            "location": "Old Trafford",
            "overall_form": [
                "L",
                "L",
                "W",
                "W",
                "W",
                "D"
            ],
            "h2h_form": [
                "D",
                "D",
                "L",
                "L",
                "D",
                "W"
            ]
        },
        "team1_last_6": [
            {
                "id": "169989",
                "date": "2019-11-02",
                "home_name": "Aston Villa",
                "away_name": "Liverpool",
                "score": "1 - 2",
                "ht_score": "",
                "ft_score": "1 - 2",
                "et_score": "",
                "league_id": "25",
                "home_id": "495",
                "away_id": "7",
                "competition_id": "2",
                "location": "Villa Park",
                "scheduled": "15:00",
                "league": {
                    "id": "25",
                    "name": "Premier League",
                    "country_id": "19"
                },
                "competition": {
                    "id": "2",
                    "name": "Premier League"
                },
                "outcomes": {
                    "half_time": null,
                    "full_time": "2",
                    "extra_time": null
                }
            },
            {
                "id": "169771",
                "date": "2019-11-02",
                "home_name": "Aston Villa",
                "away_name": "Liverpool",
                "score": "1 - 2",
                "ht_score": "1 - 0",
                "ft_score": "1 - 2",
                "et_score": "",
                "league_id": "25",
                "home_id": "495",
                "away_id": "7",
                "competition_id": "2",
                "location": "Villa Park",
                "scheduled": "15:00",
                "league": {
                    "id": "25",
                    "name": "Premier League",
                    "country_id": "19"
                },
                "competition": {
                    "id": "2",
                    "name": "Premier League"
                },
                "outcomes": {
                    "half_time": "1",
                    "full_time": "2",
                    "extra_time": null
                }
            },
            {
                "id": "169280",
                "date": "2019-10-30",
                "home_name": "Liverpool",
                "away_name": "Arsenal",
                "score": "5 - 5",
                "ht_score": "2 - 3",
                "ft_score": "",
                "et_score": "",
                "league_id": "117",
                "home_id": "7",
                "away_id": "18",
                "competition_id": "150",
                "location": "Anfield",
                "scheduled": "19:30",
                "league": {
                    "id": "117",
                    "name": "EFL Cup",
                    "country_id": "19"
                },
                "competition": {
                    "id": "150",
                    "name": "EFL Cup"
                },
                "outcomes": {
                    "half_time": "2",
                    "full_time": null,
                    "extra_time": null
                }
            },
            {
                "id": "168760",
                "date": "2019-10-27",
                "home_name": "Liverpool",
                "away_name": "Tottenham Hotspur",
                "score": "2 - 1",
                "ht_score": "0 - 1",
                "ft_score": "2 - 1",
                "et_score": "",
                "league_id": "25",
                "home_id": "7",
                "away_id": "15",
                "competition_id": "2",
                "location": null,
                "scheduled": "16:30",
                "league": {
                    "id": "25",
                    "name": "Premier League",
                    "country_id": "19"
                },
                "competition": {
                    "id": "2",
                    "name": "Premier League"
                },
                "outcomes": {
                    "half_time": "2",
                    "full_time": "1",
                    "extra_time": null
                }
            },
            {
                "id": "167688",
                "date": "2019-10-23",
                "home_name": "Genk",
                "away_name": "Liverpool",
                "score": "1 - 4",
                "ht_score": "0 - 1",
                "ft_score": "1 - 4",
                "et_score": "",
                "league_id": "232",
                "home_id": "1310",
                "away_id": "7",
                "competition_id": "244",
                "location": "Luminus Arena",
                "scheduled": "19:00",
                "league": {
                    "id": "232",
                    "name": "Group E",
                    "country_id": "84"
                },
                "competition": {
                    "id": "244",
                    "name": "Champions League"
                },
                "outcomes": {
                    "half_time": "2",
                    "full_time": "2",
                    "extra_time": null
                }
            },
            {
                "id": "167271",
                "date": "2019-10-20",
                "home_name": "Manchester United",
                "away_name": "Liverpool",
                "score": "1 - 1",
                "ht_score": "1 - 0",
                "ft_score": "1 - 1",
                "et_score": "",
                "league_id": "25",
                "home_id": "19",
                "away_id": "7",
                "competition_id": "2",
                "location": null,
                "scheduled": "15:30",
                "league": {
                    "id": "25",
                    "name": "Premier League",
                    "country_id": "19"
                },
                "competition": {
                    "id": "2",
                    "name": "Premier League"
                },
                "outcomes": {
                    "half_time": "1",
                    "full_time": "X",
                    "extra_time": null
                }
            }
        ],
        "team2_last_6": [
            {
                "id": "169987",
                "date": "2019-11-02",
                "home_name": "AFC Bournemouth",
                "away_name": "Manchester United",
                "score": "1 - 0",
                "ht_score": "",
                "ft_score": "1 - 0",
                "et_score": "",
                "league_id": "25",
                "home_id": "1",
                "away_id": "19",
                "competition_id": "2",
                "location": "Vitality Stadium",
                "scheduled": "12:30",
                "league": {
                    "id": "25",
                    "name": "Premier League",
                    "country_id": "19"
                },
                "competition": {
                    "id": "2",
                    "name": "Premier League"
                },
                "outcomes": {
                    "half_time": null,
                    "full_time": "1",
                    "extra_time": null
                }
            },
            {
                "id": "169671",
                "date": "2019-11-02",
                "home_name": "AFC Bournemouth",
                "away_name": "Manchester United",
                "score": "1 - 0",
                "ht_score": "1 - 0",
                "ft_score": "1 - 0",
                "et_score": "",
                "league_id": "25",
                "home_id": "1",
                "away_id": "19",
                "competition_id": "2",
                "location": "Vitality Stadium",
                "scheduled": "12:30",
                "league": {
                    "id": "25",
                    "name": "Premier League",
                    "country_id": "19"
                },
                "competition": {
                    "id": "2",
                    "name": "Premier League"
                },
                "outcomes": {
                    "half_time": "1",
                    "full_time": "1",
                    "extra_time": null
                }
            },
            {
                "id": "169311",
                "date": "2019-10-30",
                "home_name": "Chelsea",
                "away_name": "Manchester United",
                "score": "1 - 2",
                "ht_score": "0 - 1",
                "ft_score": "1 - 2",
                "et_score": "",
                "league_id": "117",
                "home_id": "17",
                "away_id": "19",
                "competition_id": "150",
                "location": "Stamford Bridge",
                "scheduled": "20:05",
                "league": {
                    "id": "117",
                    "name": "EFL Cup",
                    "country_id": "19"
                },
                "competition": {
                    "id": "150",
                    "name": "EFL Cup"
                },
                "outcomes": {
                    "half_time": "2",
                    "full_time": "2",
                    "extra_time": null
                }
            },
            {
                "id": "168761",
                "date": "2019-10-27",
                "home_name": "Norwich City",
                "away_name": "Manchester United",
                "score": "1 - 3",
                "ht_score": "0 - 2",
                "ft_score": "1 - 3",
                "et_score": "",
                "league_id": "25",
                "home_id": "492",
                "away_id": "19",
                "competition_id": "2",
                "location": "Carrow Road",
                "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": "167784",
                "date": "2019-10-24",
                "home_name": "Partizan Beograd",
                "away_name": "Manchester United",
                "score": "0 - 1",
                "ht_score": "0 - 1",
                "ft_score": "0 - 1",
                "et_score": "",
                "league_id": "247",
                "home_id": "152",
                "away_id": "19",
                "competition_id": "245",
                "location": "Stadion Partizana",
                "scheduled": "16:55",
                "league": {
                    "id": "247",
                    "name": "Group L",
                    "country_id": "88"
                },
                "competition": {
                    "id": "245",
                    "name": "Europa League"
                },
                "outcomes": {
                    "half_time": "2",
                    "full_time": "2",
                    "extra_time": null
                }
            },
            {
                "id": "167271",
                "date": "2019-10-20",
                "home_name": "Manchester United",
                "away_name": "Liverpool",
                "score": "1 - 1",
                "ht_score": "1 - 0",
                "ft_score": "1 - 1",
                "et_score": "",
                "league_id": "25",
                "home_id": "19",
                "away_id": "7",
                "competition_id": "2",
                "location": null,
                "scheduled": "15:30",
                "league": {
                    "id": "25",
                    "name": "Premier League",
                    "country_id": "19"
                },
                "competition": {
                    "id": "2",
                    "name": "Premier League"
                },
                "outcomes": {
                    "half_time": "1",
                    "full_time": "X",
                    "extra_time": null
                }
            }
        ],
        "h2h": [
            {
                "id": "167271",
                "date": "2019-10-20",
                "home_name": "Manchester United",
                "away_name": "Liverpool",
                "score": "1 - 1",
                "ht_score": "1 - 0",
                "ft_score": "1 - 1",
                "et_score": "",
                "league_id": "25",
                "home_id": "19",
                "away_id": "7",
                "competition_id": "2",
                "location": null,
                "scheduled": "15:30",
                "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": "128070",
                "date": "2019-02-24",
                "home_name": "Manchester United",
                "away_name": "Liverpool",
                "score": "0 - 0",
                "ht_score": "0 - 0",
                "ft_score": "0 - 0",
                "et_score": "",
                "league_id": "25",
                "home_id": "19",
                "away_id": "7",
                "competition_id": "0",
                "location": null,
                "scheduled": null,
                "outcomes": {
                    "half_time": "X",
                    "full_time": "X",
                    "extra_time": null
                },
                "competition": [],
                "league": {
                    "id": "25",
                    "name": "Premier League",
                    "country_id": "19"
                }
            },
            {
                "id": "121230",
                "date": "2018-12-16",
                "home_name": "Liverpool",
                "away_name": "Manchester United",
                "score": "3 - 1",
                "ht_score": "1 - 1",
                "ft_score": "3 - 1",
                "et_score": "",
                "league_id": "25",
                "home_id": "7",
                "away_id": "19",
                "competition_id": "0",
                "location": null,
                "scheduled": null,
                "outcomes": {
                    "half_time": "X",
                    "full_time": "1",
                    "extra_time": null
                },
                "competition": [],
                "league": {
                    "id": "25",
                    "name": "Premier League",
                    "country_id": "19"
                }
            },
            {
                "id": "97697",
                "date": "2018-07-29",
                "home_name": "Manchester United",
                "away_name": "Liverpool",
                "score": "1 - 4",
                "ht_score": "1 - 1",
                "ft_score": "1 - 4",
                "et_score": "",
                "league_id": "0",
                "home_id": "19",
                "away_id": "7",
                "competition_id": "0",
                "location": null,
                "scheduled": null,
                "outcomes": {
                    "half_time": "X",
                    "full_time": "2",
                    "extra_time": null
                },
                "competition": [],
                "league": []
            },
            {
                "id": "63233",
                "date": "2018-03-25",
                "home_name": "Liverpool",
                "away_name": "Manchester United",
                "score": "0 - 0",
                "ht_score": "",
                "ft_score": "0 - 0",
                "et_score": "",
                "league_id": "25",
                "home_id": "7",
                "away_id": "19",
                "competition_id": "0",
                "location": null,
                "scheduled": null,
                "outcomes": {
                    "half_time": null,
                    "full_time": "X",
                    "extra_time": null
                },
                "competition": [],
                "league": {
                    "id": "25",
                    "name": "Premier League",
                    "country_id": "19"
                }
            },
            {
                "id": "59011",
                "date": "2018-03-10",
                "home_name": "Manchester United",
                "away_name": "Liverpool",
                "score": "2 - 1",
                "ht_score": "2 - 0",
                "ft_score": "2 - 1",
                "et_score": "",
                "league_id": "25",
                "home_id": "19",
                "away_id": "7",
                "competition_id": "0",
                "location": null,
                "scheduled": null,
                "outcomes": {
                    "half_time": "1",
                    "full_time": "1",
                    "extra_time": null
                },
                "competition": [],
                "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.


NameTypeExampleDescription
team1objectContains the overall information about the first team.
team2objectContains the overall information about the second team.
team1_last_6objectContains the data of the last 6 games of the first team.
team2_last_6objectContains the data of the last 6 games of the second team.
h2hobjectContains that data of the last matches between the 2 teams

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