Barcelona Head-to-Head API — Free Rivalry Data for 2026

Head-to-Head Data for Free

The Barça API provides head-to-head match history between FC Barcelona and any opponent through a simple GET endpoint. You get every completed match with scores, plus a summary of wins, draws, losses, and goals — all in one clean JSON response.

No API key. No account. Completely free.

The H2H Endpoint

GET /api/h2h?team=Real Madrid

Query Parameters

Parameter	Type	Required	Description
team	string	yes	Opponent team name (partial match, min 2 chars)
season	number	no	Season year (e.g. 2025). Omit for all-time history

The team parameter supports partial matching — "Real" will match "Real Madrid", "Atlético" will match "Atlético Madrid".

Example response:

{
  "data": {
    "matches": [
      {
        "id": 42,
        "homeTeam": "Barcelona",
        "awayTeam": "Real Madrid",
        "matchDate": "2026-03-15T20:00:00.000Z",
        "homeScore": 3,
        "awayScore": 1,
        "competition": "La Liga",
        "competitionShortName": "LAL",
        "matchday": 28,
        "homeTeamImageUrl": "https://api.fc-barcelona.app/teams/barcelona.png",
        "awayTeamImageUrl": "https://api.fc-barcelona.app/teams/real-madrid.png"
      }
    ],
    "summary": {
      "played": 12,
      "wins": 6,
      "draws": 3,
      "losses": 3,
      "goalsFor": 22,
      "goalsAgainst": 15
    }
  },
  "meta": {
    "cached_at": "2026-03-21T12:00:00.000Z",
    "cache_expires_at": "2026-03-22T12:00:00.000Z"
  }
}

Matches are returned in descending order by date (most recent first). The summary is always from Barcelona's perspective.

Response Fields

Match Fields

Field	Description
id	Internal match ID
homeTeam	Home team name
awayTeam	Away team name
matchDate	Match date and time (ISO 8601)
homeScore	Home team goals
awayScore	Away team goals
competition	Full competition name
competitionShortName	Short code (LAL, UCL, CDR, SUP)
matchday	Matchday/round number

Summary Fields

Field	Description
played	Total matches played
wins	Barcelona wins
draws	Draws
losses	Barcelona losses
goalsFor	Goals scored by Barcelona
goalsAgainst	Goals conceded by Barcelona

Usage Examples

El Clásico History

const response = await fetch('https://api.fc-barcelona.app/api/h2h?team=Real Madrid');
const { data } = await response.json();

console.log(`Record vs Real Madrid: ${data.summary.wins}W ${data.summary.draws}D ${data.summary.losses}L`);
console.log(`Goals: ${data.summary.goalsFor} scored, ${data.summary.goalsAgainst} conceded`);

Season-Specific Rivalry

GET /api/h2h?team=Atlético Madrid&season=2025

Try It in the Terminal

You can also explore head-to-head data using the interactive terminal with the /h2h command:

/h2h Real Madrid        — All-time record vs Real Madrid
/h2h Atlético 2025      — 2025-26 season record vs Atlético

API Docs

View the full documentation for schema details, CORS configuration, and rate limit information.