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

Referência da API

Explore todos os endpoints da API do FC Barcelona

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

Primeiros Passos

A API do Barça é uma REST API pública e gratuita. Não é necessária autenticação — basta fazer uma requisição GET e você receberá um JSON de volta.

URL base

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

Formato de resposta

Toda resposta bem-sucedida é encapsulada em um envelope consistente:

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

O objeto meta informa quando os dados foram cacheados e quando expiram, permitindo que você gerencie o cache na sua aplicação.

O parâmetro season

A maioria dos endpoints aceita um parâmetro opcional ?season=. Passe um ano de 4 dígitos: ?season=2024 retorna dados da temporada 2024-25. Omitindo, retorna sempre a temporada atual.

Formato de erro

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

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

Rate Limiting

A API permite 100 requisições por hora por endereço IP. Toda resposta inclui headers de rate limit para você acompanhar seu uso:

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

X-RateLimit-Reset é o número de segundos até a janela ser resetada.

Ao exceder o limite, a API responde com 429 Too Many Requests:

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

Dicas para não exceder o limite

  • Faça cache das respostas — o campo meta.cache_expires_at indica por quanto tempo os dados estão frescos.
  • Evite fazer polling de endpoints em loops — a maioria dos dados é atualizada no máximo uma vez por hora.
  • Para dados de elenco e classificação (atualizados diariamente), uma única requisição por dia é suficiente.
GET/api/squad

Get Squad

Retorna o elenco completo do FC Barcelona para uma determinada temporada. Cada jogador inclui posição, número de camisa, nacionalidade, data de nascimento e estatísticas da temporada (partidas, gols, assistências).

Os jogadores são ordenados pelo número de camisa. Número 0 indica que o número de camisa não está disponível para aquela temporada.

Filtrar por posição

Use o parâmetro position para obter apenas goleiros, defensores, meias ou atacantes:

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

Exemplo com 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· padrão: 2025Season year (e.g. 2025 for the 2025-26 season). Defaults to the current season.

Resposta

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

Retorna um único jogador pelo seu ID interno. O ID do jogador vem da resposta do /api/squad (data[n].id).

Exemplo com fetch

// Primeiro busque o elenco para encontrar os IDs
const squadRes = await fetch('https://api.fc-barcelona.app/api/squad')
const { data: squad } = await squadRes.json()

// Depois busque um jogador 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()

Resposta 404

Se não existir jogador com o ID informado, a API retorna 404 Not Found:

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

Parâmetros

NameTypeRequiredDescription
idpath
integerobrigatórioInternal player ID (from the squad endpoint).
season
integeropcional· padrão: 2025Season year. Defaults to the current season.

Resposta

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

Retorna a próxima partida agendada do FC Barcelona. Útil para construir contagens regressivas ou widgets de prévia de partida.

Retorna 404 Not Found se não houver partidas futuras na temporada atual.

Exemplo com 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óxima partida: ${data.homeTeam} vs ${data.awayTeam}`)
console.log(`Local: ${data.venue}`)

Cache: Este endpoint tem um cache mais curto de 15 minutos (s-maxage=900) para manter os contadores precisos.

Parâmetros

NameTypeRequiredDescription
season
integeropcional· padrão: 2025Season year. Defaults to the current season.

Resposta

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

Retorna uma lista paginada de partidas do FC Barcelona. Você pode filtrar por competição, status e temporada.

Paginação

Use limit e offset para navegar pelos resultados. A resposta inclui um objeto pagination:

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

Filtrar próximas partidas

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

Filtrar por competição

GET /api/calendar?competition=UCL

Exemplo com 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 status

Valor Significado
scheduled Não disputada ainda
live Em andamento
completed Placar final disponível
postponed Adiada ou cancelada

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· padrão: 10Number of matches to return (1–50).
offset
integeropcional· padrão: 0Number of matches to skip for pagination.
season
integeropcional· padrão: 2025Season year. Defaults to the current season.

Resposta

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

Retorna a classificação atual da La Liga ou da UEFA Champions League, ordenada por posição.

Nota: As classificações da Copa del Rey (CDR) e Supercopa (SUP) raramente estão disponíveis.

Exemplo com 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, posição ${barca.position}`)

cURL

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

A classificação reflete os dados mais recentes e é atualizada diariamente às 07:00 UTC.

Parâmetros

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

Resposta

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

Retorna os artilheiros de uma competição, ordenados por gols em ordem decrescente. Cada entrada inclui um campo rank calculado.

Competições suportadas: Apenas LAL (La Liga) e UCL (Champions League) possuem dados de artilheiros. Copa del Rey e Supercopa não estão disponíveis.

Exemplo com 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} gols`)
})

cURL

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

Parâmetros

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

Resposta

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

Retorna o histórico de confrontos do FC Barcelona contra qualquer adversário, com um resumo de vitórias, empates, derrotas e gols.

O parâmetro team suporta correspondência parcial — "Real" corresponde a "Real Madrid", "Real Sociedad", etc.

Histórico completo

Omita o parâmetro season para obter o histórico completo:

GET /api/h2h?team=Real Madrid

Uma temporada específica

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

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

Nota: Os dados são limitados às partidas armazenadas no banco (a partir da temporada 2023-24). Dados históricos anteriores não estão disponíveis.

Parâmetros

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

Resposta

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