Build a Live Football Score App in JavaScript: Every Endpoint You Actually Need (No Fluff)

const BASE_URL = 'https://api.goal-api.com/v1';
const API_KEY  = process.env.GOAL_API_KEY;

async function get(path, params = {}) {
  const url = new URL(`${BASE_URL}${path}`);
  Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));

  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  });

  if (!res.ok) throw new Error(`GOAL API error: ${res.status}`);
  const json = await res.json();
  return json.data;
}

npm install @goalapi/sdk

import { GoalApi } from '@goalapi/sdk';

const client = new GoalApi({ apiKey: process.env.GOAL_API_KEY });

async function getLiveScores() {
  const matches = await get('/fixtures/live');

  if (!matches.length) {
    console.log('No live matches right now.');
    return;
  }

  for (const match of matches) {
    const { homeTeam, awayTeam, league, homeTeamScore, awayTeamScore, matchMinute, matchStatus } = match;
    console.log(
      `[${league.name}] ${homeTeam.name} ${homeTeamScore}–${awayTeamScore} ${awayTeam.name} | ${matchMinute || matchStatus}'`
    );
  }
}

getLiveScores();

[Premier League] Arsenal 1–0 Chelsea | 67'
[La Liga] Real Madrid 2–1 Barcelona | 81'
[Champions League] Bayern 0–0 PSG | 45+2'

async function getFixturesByDate(date) {
  // date: 'YYYY-MM-DD'
  const fixtures = await get(`/fixtures/date/${date}`);

  for (const match of fixtures) {
    const { homeTeam, awayTeam, league, kickoffUtc, matchStatus } = match;

    // Always use kickoffUtc — ISO-8601 in UTC, no offset drift
    const localKickoff = new Date(kickoffUtc).toLocaleTimeString('en-GB', {
      hour: '2-digit', minute: '2-digit', timeZoneName: 'short',
    });

    console.log(`${localKickoff} | [${league.name}] ${homeTeam.name} vs ${awayTeam.name} | ${matchStatus}`);
  }
}

const today = new Date().toISOString().slice(0, 10);
getFixturesByDate(today);

// Find a league ID by name
async function findLeague(name) {
  return get('/leagues', { search: name });
}

findLeague('premier league').then(console.log);
// Returns: [{ id: 'cmr77dvkr005nrx06lp7rvp49', name: 'Premier League', country: { name: 'England' } }, ...]

async function getStandings(leagueId) {
  const table = await get(`/standings/${leagueId}`);

  console.log(`${'Pos'.padEnd(5)}${'Team'.padEnd(28)}${'P'.padEnd(4)}${'W'.padEnd(4)}${'D'.padEnd(4)}${'L'.padEnd(4)}${'GD'.padEnd(6)}Pts`);
  console.log('─'.repeat(65));

  for (const row of table) {
    const goalDifference = Number(row.overallLeagueGF) - Number(row.overallLeagueGA);
    console.log(
      `${String(row.overallLeaguePosition).padEnd(5)}` +
      `${row.team.name.padEnd(28)}` +
      `${String(row.overallLeaguePlayed).padEnd(4)}` +
      `${String(row.overallLeagueW).padEnd(4)}` +
      `${String(row.overallLeagueD).padEnd(4)}` +
      `${String(row.overallLeagueL).padEnd(4)}` +
      `${String(goalDifference).padEnd(6)}` +
      `${row.overallLeaguePTS}`
    );
  }
}

getStandings('cmr77dvkr005nrx06lp7rvp49');  // Premier League

const homeTable = await get(`/standings/${leagueId}/home`);
const awayTable = await get(`/standings/${leagueId}/away`);
const zones     = await get(`/standings/${leagueId}/zones`);   // Promotion / relegation
const withForm  = await get(`/standings/${leagueId}/form`);    // Last 5 results column

async function getMatchTimeline(fixtureId) {
  const [goals, cards, substitutions] = await Promise.all([
    get(`/fixtures/${fixtureId}/events`),
    get(`/fixtures/${fixtureId}/cards`),
    get(`/fixtures/${fixtureId}/substitutions`),
  ]);

  const timeline = [
    ...goals.map(e => ({
      minute: e.time, icon: '⚽',
      text: `${e.homeScorer || e.awayScorer || 'Unknown'} (${e.homeScorer ? 'home' : 'away'}) ${e.score}`,
    })),
    ...cards.map(c => ({
      minute: c.time, icon: c.card.includes('red') ? '🟥' : '🟨',
      text: `${c.homeFault || c.awayFault || 'Unknown'} (${c.homeFault ? 'home' : 'away'})`,
    })),
    ...substitutions.map(s => ({
      minute: s.time, icon: '🔄',
      text: `${s.substitution} (${s.team})`,   // "player off | player on"
    })),
  ].sort((a, b) => parseInt(a.minute) - parseInt(b.minute));

  for (const event of timeline) {
    console.log(`${event.icon} ${event.minute}' ${event.text}`);
  }
}

const cards         = await get(`/fixtures/${fixtureId}/cards`);
const substitutions = await get(`/fixtures/${fixtureId}/substitutions`);

async function getOdds(fixtureId) {
  const odds = await get(`/fixtures/${fixtureId}/odds`);

  for (const book of odds) {
    const { bookmaker, odd1, oddX, odd2, overUnder } = book;

    console.log(`\n[${bookmaker}]`);
    console.log(`  1X2 — Home: ${odd1} | Draw: ${oddX} | Away: ${odd2}`);

    if (overUnder) {
      for (const line of ['0.5', '1.5', '2.5', '3.5']) {
        console.log(`  O/U ${line}: over=${overUnder[`o+${line}`]} under=${overUnder[`u+${line}`]}`);
      }
    }
  }
}

const liveOdds = await get(`/fixtures/${fixtureId}/live-odds`);

// Search for a player first
async function searchPlayer(name) {
  return get('/players/search', { q: name });
}

// Then pull their season stats
async function getPlayerStats(playerId) {
  const stats = await get(`/players/${playerId}/statistics`);
  const { goals, assists, matchPlayed, minutes, yellowCards, redCards } = stats.performance;

  console.log(`Goals:      ${goals}`);
  console.log(`Assists:    ${assists}`);
  console.log(`Apps:       ${matchPlayed} (${minutes} mins)`);
  console.log(`Cards:     🟨 ${yellowCards}  🟥 ${redCards}`);
}

const results = await searchPlayer('Erling Haaland');
await getPlayerStats(results[0].id);

const comparison = await get('/players/compare', { ids: `${id1},${id2}` });
const topScorers = await get(`/leagues/${leagueId}/top-scorers`);
const topAssists = await get('/players/top/assists');

// Step 1: Exchange your API key for a connection token (server-side only)
async function getWsToken() {
  const res = await fetch('https://api.goal-api.com/v1/ws/token', {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.GOAL_API_KEY}` },
  });
  const { data } = await res.json();
  return data.token;  // valid for 60s, single-use
}

// Step 2: Connect, authenticate, subscribe
async function connectToLiveMatch(fixtureId) {
  const token = await getWsToken();
  const ws    = new WebSocket(`wss://api.goal-api.com/ws?wsToken=${token}`);

  ws.addEventListener('open', () => {
    ws.send(JSON.stringify({ type: 'auth', token }));
  });

  ws.addEventListener('message', (event) => {
    const msg = JSON.parse(event.data);

    if (msg.type === 'auth_success') {
      console.log('Connected. Subscribing to match', fixtureId);
      ws.send(JSON.stringify({
        type: 'subscribe',
        resource: 'match',
        matchId: String(fixtureId),
      }));
    }

    if (msg.type === 'match_update') {
      const { match_hometeam_score, match_awayteam_score, goalscorer } = msg.data;
      console.log(`Score: ${match_hometeam_score}–${match_awayteam_score}`);
      goalscorer?.forEach(g => console.log(`⚽ GOAL: ${g.home_scorer || g.away_scorer} (${g.time}')`));
    }

    if (msg.type === 'error') {
      console.error('WS error:', msg.error.code, msg.error.message);
      // msg.error.category: 'authentication' | 'rate_limit' | ...
    }
  });

  // Always handle close — networks drop
  ws.addEventListener('close', () => {
    console.log('Connection closed. Reconnecting in 5s...');
    setTimeout(() => connectToLiveMatch(fixtureId), 5000);
  });
}

async function getWithHeaders(path) {
  const res = await fetch(`${BASE_URL}${path}`, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  });

  const remaining = res.headers.get('X-RateLimit-Remaining');
  const limit     = res.headers.get('X-RateLimit-Limit');
  const reset     = res.headers.get('X-RateLimit-Reset');
  console.log(`Quota: ${remaining}/${limit} | Resets: ${reset}`);

  if (res.status === 429) {
    const body      = await res.json();
    const errorCode = body?.code;

    if (errorCode === 'BURST_LIMIT_EXCEEDED') {
      // Fired > 130 req/s — back off for 1 second
      console.warn('Burst limit hit — retrying in 1s');
      await new Promise(r => setTimeout(r, 1000));
    } else {
      // QUOTA_EXCEEDED — daily allowance gone
      const retryAfter = parseInt(reset) - Math.floor(Date.now() / 1000);
      console.warn(`Daily quota hit. Retry in ${retryAfter}s`);
    }
    return null;
  }

  if (!res.ok) throw new Error(`API error: ${res.status}`);
  return (await res.json()).data;
}