FC Barcelona
BarçaAPI
🇬🇧🇧🇷🇪🇸
v1.0Free · No auth required

API Reference

Explore all FC Barcelona API endpoints

Base URLhttps://api.fc-barcelona.app/api

Getting Started

The Barça API is a free, public REST API. No API key or authentication is required — just make a GET request and you'll get JSON back.

Base URL

https://api.fc-barcelona.app/api

Response format

Every successful response is wrapped in a consistent envelope:

{
  "data": { ... },
  "meta": {
    "cached_at": "2026-04-03T10:00:00.000Z",
    "cache_expires_at": "2026-04-04T10:00:00.000Z"
  }
}

The meta object tells you when the data was cached and when it expires, so you can decide whether to cache it on your end.

The season parameter

Most endpoints accept an optional ?season= query parameter. Pass a 4-digit year: ?season=2024 returns data for the 2024-25 season. Omitting it always returns the current season.

Error format

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Player not found"
  }
}

Error codes: NOT_FOUND (404), VALIDATION_ERROR (400), RATE_LIMITED (429).

Rate Limiting

The API allows 100 requests per hour per IP address. Every response includes rate limit headers so you can track your usage:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 3412

X-RateLimit-Reset is the number of seconds until the window resets.

When you exceed the limit, the API responds with 429 Too Many Requests:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Please wait before retrying."
  }
}

Tips to stay within the limit

  • Cache responses on your end — the meta.cache_expires_at field tells you how long the data is fresh.
  • Avoid polling endpoints in tight loops; most data updates at most once per hour.
  • For squad and standings data (updated daily), a single daily fetch is enough.
GET/api/squad

Get Squad

Returns the full FC Barcelona squad for a given season. Each player includes their position, shirt number, nationality, date of birth, and season statistics (appearances, goals, assists).

Players are ordered by shirt number ascending. Shirt number 0 means the number is unavailable for that season.

Filter by position

Use the position parameter to get only goalkeepers, defenders, midfielders, or forwards:

GET /api/squad?position=GK
GET /api/squad?position=FW

Fetch example

const res = await fetch('https://api.fc-barcelona.app/api/squad')
const { data } = await res.json()

data.forEach(player => {
  console.log(`#${player.number} ${player.name} — ${player.position}`)
})

cURL

curl https://api.fc-barcelona.app/api/squad?position=MF

Parameters

NameTypeRequiredDescription
position
GKDFMFFW
optionalFilter players by position.
season
integeroptional· default: 2025Season year (e.g. 2025 for the 2025-26 season). Defaults to the current season.

Response

200 OK
{
  "data": [
    {
      "id": 1,
      "name": "Marc-André ter Stegen",
      "number": 1,
      "position": "GK",
      "nationality": "Germany",
      "dateOfBirth": "1992-04-30",
      "isCaptain": false,
      "appearances": 28,
      "goals": 0,
      "assists": 0
    },
    {
      "id": 2,
      "name": "Lamine Yamal",
      "number": 19,
      "position": "FW",
      "nationality": "Spain",
      "dateOfBirth": "2007-07-13",
      "isCaptain": false,
      "appearances": 32,
      "goals": 14,
      "assists": 18
    }
  ],
  "meta": {
    "cached_at": "2026-04-03T10:00:00.000Z",
    "cache_expires_at": "2026-04-04T10:00:00.000Z"
  }
}
GET/api/player/{id}

Get Player

Returns a single player by their internal ID. The player ID comes from the /api/squad response (data[n].id).

Fetch example

// First get the squad to find player IDs
const squadRes = await fetch('https://api.fc-barcelona.app/api/squad')
const { data: squad } = await squadRes.json()

// Then fetch a specific player
const player = squad.find(p => p.name === 'Lamine Yamal')
const playerRes = await fetch(`https://api.fc-barcelona.app/api/player/${player.id}`)
const { data } = await playerRes.json()

404 response

If no player with the given ID exists, the API returns a 404 Not Found with:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Player not found"
  }
}

Parameters

NameTypeRequiredDescription
idpath
integerrequiredInternal player ID (from the squad endpoint).
season
integeroptional· default: 2025Season year. Defaults to the current season.

Response

200 OK
{
  "data": {
    "id": 2,
    "name": "Lamine Yamal",
    "number": 19,
    "position": "FW",
    "nationality": "Spain",
    "dateOfBirth": "2007-07-13",
    "isCaptain": false,
    "appearances": 32,
    "goals": 14,
    "assists": 18
  },
  "meta": {
    "cached_at": "2026-04-03T10:00:00.000Z",
    "cache_expires_at": "2026-04-04T10:00:00.000Z"
  }
}
GET/api/next-match

Get Next Match

Returns the next scheduled FC Barcelona match. Useful for building countdown timers or match preview widgets.

Returns 404 Not Found if there is no upcoming match in the current season.

Fetch example

const res = await fetch('https://api.fc-barcelona.app/api/next-match')
const { data } = await res.json()

const kickoff = new Date(data.matchDate)
const now = new Date()
const msUntilKickoff = kickoff - now

console.log(`Next match: ${data.homeTeam} vs ${data.awayTeam}`)
console.log(`Venue: ${data.venue}`)

Cache: This endpoint has a shorter cache of 15 minutes (s-maxage=900) to keep countdown timers accurate.

Parameters

NameTypeRequiredDescription
season
integeroptional· default: 2025Season year. Defaults to the current season.

Response

200 OK
{
  "data": {
    "id": 101,
    "homeTeam": "Barcelona",
    "homeTeamImageUrl": "https://api.fc-barcelona.app/images/teams/barcelona.png",
    "awayTeam": "Real Madrid",
    "awayTeamImageUrl": "https://api.fc-barcelona.app/images/teams/real-madrid.png",
    "matchDate": "2026-04-12T19:00:00.000Z",
    "venue": "Estadi Olímpic Lluís Companys",
    "status": "scheduled",
    "homeScore": null,
    "awayScore": null,
    "matchday": 31,
    "competition": "La Liga",
    "competitionShortName": "LAL",
    "competitionImageUrl": "https://api.fc-barcelona.app/images/competitions/laliga.png"
  },
  "meta": {
    "cached_at": "2026-04-03T10:00:00.000Z",
    "cache_expires_at": "2026-04-03T11:00:00.000Z"
  }
}
GET/api/calendar

Get Calendar

Returns a paginated list of FC Barcelona matches. You can filter by competition, status, and season.

Pagination

Use limit and offset to page through results. The response includes a pagination object:

{
  "pagination": {
    "total": 48,
    "limit": 10,
    "offset": 0
  }
}

Filter upcoming matches

GET /api/calendar?status=scheduled&limit=5

Filter by competition

GET /api/calendar?competition=UCL

Fetch example

const res = await fetch('https://api.fc-barcelona.app/api/calendar?status=completed&limit=10')
const { data } = await res.json()

data.matches.forEach(match => {
  console.log(`${match.homeTeam} ${match.homeScore}–${match.awayScore} ${match.awayTeam}`)
})

Match status values

Value Meaning
scheduled Not yet played
live In progress
completed Final score available
postponed Postponed or cancelled

Parameters

NameTypeRequiredDescription
competition
LALUCLCDRSUP
optionalFilter by competition. LAL = La Liga, UCL = Champions League, CDR = Copa del Rey, SUP = Supercopa.
status
scheduledcompletedlivepostponed
optionalFilter by match status.
limit
integeroptional· default: 10Number of matches to return (1–50).
offset
integeroptional· default: 0Number of matches to skip for pagination.
season
integeroptional· default: 2025Season year. Defaults to the current season.

Response

200 OK
{
  "data": {
    "matches": [
      {
        "id": 101,
        "homeTeam": "Barcelona",
        "homeTeamImageUrl": "https://api.fc-barcelona.app/images/teams/barcelona.png",
        "awayTeam": "Real Madrid",
        "awayTeamImageUrl": "https://api.fc-barcelona.app/images/teams/real-madrid.png",
        "matchDate": "2026-04-12T19:00:00.000Z",
        "venue": "Estadi Olímpic Lluís Companys",
        "status": "scheduled",
        "homeScore": null,
        "awayScore": null,
        "matchday": 31,
        "competition": "La Liga",
        "competitionShortName": "LAL",
        "competitionImageUrl": "https://api.fc-barcelona.app/images/competitions/laliga.png"
      }
    ],
    "pagination": {
      "total": 48,
      "limit": 10,
      "offset": 0
    }
  },
  "meta": {
    "cached_at": "2026-04-03T10:00:00.000Z",
    "cache_expires_at": "2026-04-03T10:30:00.000Z"
  }
}
GET/api/standings

Get Standings

Returns the current league standings for La Liga or the UEFA Champions League, sorted by position.

Note: Copa del Rey (CDR) and Supercopa (SUP) standings are rarely available.

Fetch example

const res = await fetch('https://api.fc-barcelona.app/api/standings?competition=UCL')
const { data } = await res.json()

const barca = data.find(team => team.team === 'Barcelona')
console.log(`Barcelona: ${barca.points} pts, position ${barca.position}`)

cURL

curl 'https://api.fc-barcelona.app/api/standings?competition=LAL'

The standings reflect the latest data and are refreshed daily at 07:00 UTC.

Parameters

NameTypeRequiredDescription
competition
LALUCLCDRSUP
optional· default: LALCompetition short name. Defaults to LAL (La Liga).
season
integeroptional· default: 2025Season year. Defaults to the current season.

Response

200 OK
{
  "data": [
    {
      "position": 1,
      "team": "Barcelona",
      "teamImageUrl": "https://api.fc-barcelona.app/images/teams/barcelona.png",
      "played": 30,
      "won": 22,
      "drawn": 4,
      "lost": 4,
      "goalsFor": 74,
      "goalsAgainst": 32,
      "goalDifference": 42,
      "points": 70,
      "competition": "La Liga"
    },
    {
      "position": 2,
      "team": "Real Madrid",
      "teamImageUrl": "https://api.fc-barcelona.app/images/teams/real-madrid.png",
      "played": 30,
      "won": 20,
      "drawn": 5,
      "lost": 5,
      "goalsFor": 65,
      "goalsAgainst": 35,
      "goalDifference": 30,
      "points": 65,
      "competition": "La Liga"
    }
  ],
  "meta": {
    "cached_at": "2026-04-03T10:00:00.000Z",
    "cache_expires_at": "2026-04-03T16:00:00.000Z"
  }
}
GET/api/scorers

Get Top Scorers

Returns the top scorers for a competition, sorted by goals descending. Each entry includes a calculated rank field.

Supported competitions: Only LAL (La Liga) and UCL (Champions League) have scorer data. Copa del Rey and Supercopa are not available.

Fetch example

const res = await fetch('https://api.fc-barcelona.app/api/scorers?competition=UCL')
const { data } = await res.json()

data.forEach(scorer => {
  console.log(`${scorer.rank}. ${scorer.playerName} (${scorer.team}) — ${scorer.goals} goals`)
})

cURL

curl 'https://api.fc-barcelona.app/api/scorers?competition=LAL&season=2024'

Parameters

NameTypeRequiredDescription
competition
LALUCL
optional· default: LALCompetition short name. Only LAL and UCL are supported.
season
integeroptional· default: 2025Season year. Defaults to the current season.

Response

200 OK
{
  "data": [
    {
      "rank": 1,
      "playerName": "Robert Lewandowski",
      "team": "Barcelona",
      "teamImageUrl": "https://api.fc-barcelona.app/images/teams/barcelona.png",
      "goals": 24,
      "assists": 8,
      "penalties": 3,
      "playedMatches": 28,
      "competition": "La Liga",
      "competitionShortName": "LAL"
    },
    {
      "rank": 2,
      "playerName": "Kylian Mbappé",
      "team": "Real Madrid",
      "teamImageUrl": "https://api.fc-barcelona.app/images/teams/real-madrid.png",
      "goals": 21,
      "assists": 6,
      "penalties": 2,
      "playedMatches": 29,
      "competition": "La Liga",
      "competitionShortName": "LAL"
    }
  ],
  "meta": {
    "cached_at": "2026-04-03T10:00:00.000Z",
    "cache_expires_at": "2026-04-03T16:00:00.000Z"
  }
}
GET/api/h2h

Head-to-Head

Returns FC Barcelona's head-to-head record against any opponent, plus a summary of wins, draws, losses, and goals.

The team parameter supports partial matching — "Real" matches "Real Madrid", "Real Sociedad", etc.

All-time record

Omit the season parameter to get the full historical record:

GET /api/h2h?team=Real Madrid

Single season

GET /api/h2h?team=Atletico&season=2025

Fetch example

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

const { summary, matches } = data
console.log(`Played: ${summary.played} — W${summary.wins} D${summary.draws} L${summary.losses}`)
console.log(`Goals: ${summary.goalsFor}–${summary.goalsAgainst}`)

Note: Data is limited to matches stored in the database (from the 2023-24 season onwards). Historical data before that period is not available.

Parameters

NameTypeRequiredDescription
team
stringrequiredOpponent team name. Partial match is supported (e.g. "Real" matches "Real Madrid").
season
integeroptionalSeason year. Omit to return all-time results.

Response

200 OK
{
  "data": {
    "matches": [
      {
        "id": 95,
        "homeTeam": "Barcelona",
        "homeTeamImageUrl": "https://api.fc-barcelona.app/images/teams/barcelona.png",
        "awayTeam": "Real Madrid",
        "awayTeamImageUrl": "https://api.fc-barcelona.app/images/teams/real-madrid.png",
        "matchDate": "2026-03-01T20:00:00.000Z",
        "venue": "Estadi Olímpic Lluís Companys",
        "status": "completed",
        "homeScore": 3,
        "awayScore": 2,
        "matchday": 26,
        "competition": "La Liga",
        "competitionShortName": "LAL",
        "competitionImageUrl": "https://api.fc-barcelona.app/images/competitions/laliga.png"
      }
    ],
    "summary": {
      "played": 12,
      "wins": 5,
      "draws": 3,
      "losses": 4,
      "goalsFor": 18,
      "goalsAgainst": 15
    }
  },
  "meta": {
    "cached_at": "2026-04-03T10:00:00.000Z",
    "cache_expires_at": "2026-04-03T16:00:00.000Z"
  }
}