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

Referencia de la API

Explora todos los endpoints de la API del FC Barcelona

URL Basehttps://api.fc-barcelona.app/api

Primeros pasos

La API del Barça es una REST API pública y gratuita. No se requiere autenticación — solo haz una solicitud GET y recibirás un JSON de vuelta.

URL base

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

Formato de respuesta

Cada respuesta exitosa viene envuelta en un sobre consistente:

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

El objeto meta indica cuándo se almacenaron los datos en caché y cuándo expiran, para que puedas gestionarlo en tu aplicación.

El parámetro season

La mayoría de los endpoints aceptan un parámetro opcional ?season=. Pasa un año de 4 dígitos: ?season=2024 devuelve datos de la temporada 2024-25. Sin él, siempre devuelve la temporada actual.

Formato de error

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

Códigos de error: NOT_FOUND (404), VALIDATION_ERROR (400), RATE_LIMITED (429).

Rate Limiting

La API permite 100 solicitudes por hora por dirección IP. Cada respuesta incluye headers de rate limit para que puedas monitorear tu uso:

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

X-RateLimit-Reset es el número de segundos hasta que se reinicia la ventana.

Al superar el límite, la API responde con 429 Too Many Requests:

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

Consejos para mantenerte dentro del límite

  • Almacena en caché las respuestas — el campo meta.cache_expires_at indica hasta cuándo los datos son frescos.
  • Evita hacer polling en bucles cerrados; la mayoría de los datos se actualiza como máximo una vez por hora.
  • Para datos de plantilla y clasificación (actualizados diariamente), una sola solicitud diaria es suficiente.
GET/api/squad

Get Squad

Devuelve la plantilla completa del FC Barcelona para una temporada determinada. Cada jugador incluye posición, número de camiseta, nacionalidad, fecha de nacimiento y estadísticas de la temporada (partidos, goles, asistencias).

Los jugadores están ordenados por número de camiseta. El número 0 indica que el número no está disponible para esa temporada.

Filtrar por posición

Usa el parámetro position para obtener solo porteros, defensas, centrocampistas o delanteros:

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

Ejemplo con fetch

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

Parámetros

NameTypeRequiredDescription
position
GKDFMFFW
opcionalFilter players by position.
season
integeropcional· predeterminado: 2025Season year (e.g. 2025 for the 2025-26 season). Defaults to the current season.

Respuesta

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

Devuelve un único jugador por su ID interno. El ID del jugador proviene de la respuesta de /api/squad (data[n].id).

Ejemplo con fetch

// Primero obtén la plantilla para encontrar los IDs
const squadRes = await fetch('https://api.fc-barcelona.app/api/squad')
const { data: squad } = await squadRes.json()

// Luego busca un jugador específico
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()

Respuesta 404

Si no existe ningún jugador con el ID indicado, la API devuelve 404 Not Found:

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

Parámetros

NameTypeRequiredDescription
idpath
integerrequeridoInternal player ID (from the squad endpoint).
season
integeropcional· predeterminado: 2025Season year. Defaults to the current season.

Respuesta

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

Devuelve el próximo partido programado del FC Barcelona. Útil para construir temporizadores de cuenta regresiva o widgets de vista previa de partido.

Devuelve 404 Not Found si no hay próximos partidos en la temporada actual.

Ejemplo con fetch

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(`Próximo partido: ${data.homeTeam} vs ${data.awayTeam}`)
console.log(`Estadio: ${data.venue}`)

Caché: Este endpoint tiene un caché más corto de 15 minutos (s-maxage=900) para mantener los temporizadores precisos.

Parámetros

NameTypeRequiredDescription
season
integeropcional· predeterminado: 2025Season year. Defaults to the current season.

Respuesta

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

Devuelve una lista paginada de partidos del FC Barcelona. Puedes filtrar por competición, estado y temporada.

Paginación

Usa limit y offset para navegar por los resultados. La respuesta incluye un objeto pagination:

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

Filtrar próximos partidos

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

Filtrar por competición

GET /api/calendar?competition=UCL

Ejemplo con fetch

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}`)
})

Valores de estado

Valor Significado
scheduled Aún no jugado
live En progreso
completed Resultado final disponible
postponed Aplazado o cancelado

Parámetros

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

Respuesta

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

Devuelve la clasificación actual de La Liga o la UEFA Champions League, ordenada por posición.

Nota: Las clasificaciones de la Copa del Rey (CDR) y Supercopa (SUP) raramente están disponibles.

Ejemplo con fetch

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, posición ${barca.position}`)

cURL

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

La clasificación refleja los datos más recientes y se actualiza diariamente a las 07:00 UTC.

Parámetros

NameTypeRequiredDescription
competition
LALUCLCDRSUP
opcional· predeterminado: LALCompetition short name. Defaults to LAL (La Liga).
season
integeropcional· predeterminado: 2025Season year. Defaults to the current season.

Respuesta

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

Devuelve los máximos goleadores de una competición, ordenados por goles de forma descendente. Cada entrada incluye un campo rank calculado.

Competiciones disponibles: Solo LAL (La Liga) y UCL (Champions League) tienen datos de goleadores. Copa del Rey y Supercopa no están disponibles.

Ejemplo con fetch

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} goles`)
})

cURL

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

Parámetros

NameTypeRequiredDescription
competition
LALUCL
opcional· predeterminado: LALCompetition short name. Only LAL and UCL are supported.
season
integeropcional· predeterminado: 2025Season year. Defaults to the current season.

Respuesta

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

Devuelve el historial de enfrentamientos del FC Barcelona contra cualquier rival, con un resumen de victorias, empates, derrotas y goles.

El parámetro team admite coincidencia parcial — "Real" coincide con "Real Madrid", "Real Sociedad", etc.

Historial completo

Omite el parámetro season para obtener el historial completo:

GET /api/h2h?team=Real Madrid

Una temporada específica

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

Ejemplo con fetch

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(`Jugados: ${summary.played} — V${summary.wins} E${summary.draws} D${summary.losses}`)
console.log(`Goles: ${summary.goalsFor}–${summary.goalsAgainst}`)

Nota: Los datos están limitados a los partidos almacenados en la base de datos (desde la temporada 2023-24). No hay datos históricos anteriores.

Parámetros

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

Respuesta

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"
  }
}