Head 2 Head

  1. Endpoint
  2. Parameters
  3. Response
  4. Team1 And Team2
  5. Team1_last_6 And Team2_last_6
  6. H2h
  7. Fixture

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

If you are looking to just get the last matches of a single team you can use our dedicated football API endpoint for getting teams last matches.

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. 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:


GET:

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


NameTypeRequiredExampleDescription
langstringarThe language code of the language in which we want the data in.
team1_idnumber17The ID of the first team that we are comparing.
team2_idnumber119The 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.


NameTypeExampleDescription
fixtureobjectThe next match that the teams will be playing agains each other.
h2hobjectContains that data of the last matches between the 2 teams
team1objectContains the overall information about the first team.
team1_last_6objectContains the data of the last 6 games of the first team.
team2objectContains the overall information about the second team.
team2_last_6objectContains 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.


Didn't find what you need?

Do no hesitate to contact us. We will get back to you as soon as possible.