Barcelona Next Match API Endpoint — Free & Real-Time 2026

The Next Match Endpoint

One of the most useful endpoints in the Barça API is /api/next-match. It returns the immediately upcoming FC Barcelona fixture — giving you team names, match date, venue, competition, and matchday number in a single call.

Free to use, no API key required.

Making the Request

GET /api/next-match

curl https://api.fc-barcelona.app/api/next-match

Response Structure

{
  "data": {
    "id": 15,
    "homeTeam": "FC Barcelona",
    "awayTeam": "Real Madrid",
    "matchDate": "2026-03-22T21:00:00Z",
    "venue": "Spotify Camp Nou",
    "competition": "La Liga",
    "matchday": 29,
    "status": "scheduled"
  }
}

If there is no upcoming match, data will be null.

Key Fields Explained

matchDate

The match date is returned in ISO 8601 format (UTC). This is the most important field for building countdown timers or calendar integrations.

Always convert to local time before displaying:

const matchDate = new Date(data.matchDate);
const localTime = matchDate.toLocaleString('en-US', {
  weekday: 'long',
  year: 'numeric',
  month: 'long',
  day: 'numeric',
  hour: '2-digit',
  minute: '2-digit',
  timeZoneName: 'short'
});
console.log(localTime); // "Saturday, March 22, 2026 at 10:00 PM CET"

status

Can be scheduled (upcoming) or completed (finished). The /api/next-match endpoint always returns the first scheduled match, so status will always be scheduled unless a match just kicked off.

homeTeam / awayTeam

Either team can be FC Barcelona depending on whether it is a home or away fixture.

Building a Live Countdown

The next match endpoint is perfect for a real-time countdown widget:

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

  if (!data) {
    document.getElementById('countdown').textContent = 'No upcoming match';
    return;
  }

  const matchDate = new Date(data.matchDate);

  setInterval(() => {
    const now = new Date();
    const diff = matchDate - now;

    if (diff <= 0) {
      document.getElementById('countdown').textContent = 'Match underway!';
      return;
    }

    const days = Math.floor(diff / 86400000);
    const hours = Math.floor((diff % 86400000) / 3600000);
    const minutes = Math.floor((diff % 3600000) / 60000);
    const seconds = Math.floor((diff % 60000) / 1000);

    document.getElementById('countdown').textContent =
      `${days}d ${hours}h ${minutes}m ${seconds}s`;
  }, 1000);
}

startCountdown();

Calendar Integration

To show the match on a calendar, use the matchDate to create an ICS event or integrate with Google Calendar:

const icsContent = [
  'BEGIN:VCALENDAR',
  'VERSION:2.0',
  'BEGIN:VEVENT',
  `DTSTART:${data.matchDate.replace(/[-:]/g, '').split('.')[0]}Z`,
  `SUMMARY:${data.homeTeam} vs ${data.awayTeam}`,
  `LOCATION:${data.venue}`,
  'END:VEVENT',
  'END:VCALENDAR'
].join('\r\n');

Notifications with Service Workers

Use the match date to schedule a browser notification before the match:

const timeUntilMatch = new Date(data.matchDate) - new Date();
const notifyBefore = 30 * 60 * 1000; // 30 minutes

setTimeout(() => {
  new Notification('Barcelona match starting soon!', {
    body: `${data.homeTeam} vs ${data.awayTeam} — ${data.venue}`
  });
}, timeUntilMatch - notifyBefore);

Try It Live

The interactive terminal shows the next match with a live countdown. Run /next-match to see it. The full API docs have the complete response schema.