Head to Head

Learn how to get the record for head-to-head fixtures.

We'll cover the following

Consider the case of two friends sitting together and discussing whose favorite team is better. Time to back up these opinions with some facts using Api-Football. We can see the head-to-head records for any two teams by using this API.

Get results of head-to-head fixtures

The Head to Head endpoint is used to get the results of fixtures between any two teams. It provides other information as well, such as the number of goals scored by each team and the match venue. Its base URI is https://v3.football.api-sports.io/fixtures/headtohead.

Request parameters

The following query parameters can be used with this endpoint:

Parameters

Type

Category

Description

h2h

String

Required

This is the ID of the teams separated by "-." We can get the IDs of the teams using the Teams information endpoint.

date

String

Optional

This is the date of the fixture we want to see. The format is "YYYY-MM-DD."

league

Integer

Optional

This is the ID of the league we want fixtures from. This ID can be obtained using the Leagues endpoint.

season

Integer

Optional

This is the year we want to see the fixtures for. The format is "YYYY."

last

Integer

Optional

This indicates the number of past fixtures we want to see the stats for.

next

Integer

Optional

This indicates the number of future fixtures we want to see the information for.

from

String

Optional

This is the date we want the fixtures' data to begin from. The format is "YYYY-MM-DD."

to

String

Optional

This is the termination date for the fixtures' data. The format is "YYYY-MM-DD."

status

String

Optional

This indicates the status of the fixtures.

timezone

String

Optional

This is the timezone we want to see the fixtures for. Valid timezones can be obtained using the Timezone endpoint as explained in the "Support Endpoints" lesson in the Appendix.

Note: To look at the list of valid statuses for this endpoint, click hereUntitledConcept1.

Using just the h2h query parameter with this endpoint provides us the record of all the fixtures between two teams. The code to get information about all fixtures between two teams is in the widget below. Click the “Run” button to retrieve this information.

Press + to interact
const endpointUrl = new URL('https://v3.football.api-sports.io/fixtures/headtohead');
const queryParameters = new URLSearchParams({
  h2h: '33-34' // 33 is the id for Manchester United & 34 is for Newcastle United
});
headerParameters = {
  'x-rapidapi-host': 'v3.football.api-sports.io',
  'x-rapidapi-key': '{{API_KEY}}'
}
const options = {
  method: 'GET',
  headers: headerParameters
};
async function fetchH2HFixtureStats() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } 
  catch (error) {
    printError(error);
  }
}
fetchH2HFixtureStats();

Here is a brief explanation of the code in the above widget:

  • Line 1: We set the URL to https://v3.football.api-sports.io/fixtures/headtohead.

  • Lines 3–10: We define the query parameters and header parameters. We can replace 33-34 with the team IDs of other teams to get the information for their head-to-head fixtures.

  • Lines 12–15: We set the request type and appropriate header.

  • Lines 17–26: We define a function, fetchH2HFixtureStats(). It calls the endpoint and prints the response.

Note: The teams’ IDs can be retrieved using the Teams information endpoint, as explained in the Teams Information lesson.

We can also filter the information we get in response by using other parameters with the h2h parameter. For example, we can get the head-to-head records for two teams for a specific league or cup by combining the league and h2h parameters as in the widget below. The league and season parameters have been added in the code below. Click “Run” to make the GET request.

Note: The season parameter is required when the league parameter is used with this endpoint.

Press + to interact
const date = new Date();
const endpointUrl = new URL('https://v3.football.api-sports.io/fixtures/headtohead');
const queryParameters = new URLSearchParams({
  h2h: '33-34', // 33 is the id for Manchester United & 34 is for Newcastle United
  league: '39', // 39 is the league id for England's Premier League
  season: date.getFullYear()
});
headerParameters = {
  'x-rapidapi-host': 'v3.football.api-sports.io',
  'x-rapidapi-key': '{{API_KEY}}'
}
const options = {
  method: 'GET',
  headers: headerParameters
};
async function fetchH2HFixtureStats() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } 
  catch (error) {
    printError(error);
  }
}
fetchH2HFixtureStats();

We've added a few query parameters to filter the response we received in the prior widget. We can change the league ID in line 6 to get information for head-to-head fixtures for the same teams in a different competition.

Note: The league ID can be retrieved using the Leagues endpoint, as explained in the Support Endpoints lesson in the Appendix.

Similarly, we may obtain the head-to-head records for two teams in all competitions by removing the league parameter in line 6.

Response fields

The table below contains some important response fields of this endpoint:

Response Fields

Type

Description

fixture

Object

This object contains information like ID, date, and time of the fixtures.

league

Object

This object contains information about the league in which the fixture has been scheduled.

teams

Object

This object contains information like the ID, name, and a link for the logo of the teams participating in the fixture.

goals

Object

This object contains information about the goals scored in the fixture.

score

Object

This object contains information about the goals scored at half-time, full-time, extra-time, and the goals scored in penalties.

Note: The details about the elements in fixture and league objects are discussed in the Response Elements lesson in the Appendix.