Basketball API / Blog

Build a live NBA scoreboard

4 October 2026 · 7 min read

A scoreboard is the smallest useful thing to build on basketball data. It is also where most tutorials leak an API key. Here is the whole thing, the part they skip included.

What live returns

One endpoint, no parameters:

curl -H "X-RapidAPI-Key: YOUR_KEY" \
  -H "X-RapidAPI-Host: nba206.p.rapidapi.com" \
  "https://nba206.p.rapidapi.com/games/live"

When nothing is being played you get this. Design for it first, because it is the answer most of the day:

{ "data": [], "meta": { "season": "2026-27" } }

A game in play is the same object every other game endpoint returns, with three fields that only mean something while it is on:

FieldWhile in play
statuslive, or halftime during the break
periodThe quarter, 1 to 4, then 5 for the first overtime, 6 for the second
clockTime left in the period as a string, "02:13"

Both are null before tip-off and after the final buzzer, so a finished game never carries a stale clock. Each team comes with a logoUrl you can put straight into an img tag.

Print the period the way people say it

Nobody says "period 5". The game detail already labels its periods Q1 to Q4, then OT, OT2 and so on, and the scoreboard should match:

const periodLabel = (g) => {
  if (g.status === 'halftime') return 'Half';
  if (g.period <= 4) return 'Q' + g.period;
  return g.period === 5 ? 'OT' : 'OT' + (g.period - 4);
};

The same code works for the EuroLeague. Its quarters are ten minutes rather than twelve, so the clock starts lower, and nothing else changes.

Poll every 30 seconds

Every game in play is refreshed every 30 seconds. Asking more often cannot get you fresher data, it only spends your quota. The live response also carries cache-control: max-age=15, the shortest interval at which a repeat request can return anything new. Thirty seconds is the right number for a scoreboard, and sixty is fine for a widget in a sidebar.

Your key cannot go in the browser

If the page calls the API with fetch, your key is in the page source and in the network tab of anyone who opens developer tools. Keys get scraped from public sites automatically. Put a small server in front. It holds the key, and your quota is spent once per poll however many people have the page open:

// server.js (Node 18 or later, no dependencies)
import { createServer } from 'node:http';
import { readFile } from 'node:fs/promises';

const KEY = process.env.RAPIDAPI_KEY;
const HOST = 'nba206.p.rapidapi.com';

createServer(async (req, res) => {
  if (req.url === '/api/live') {
    const upstream = await fetch('https://' + HOST + '/games/live', {
      headers: { 'X-RapidAPI-Key': KEY, 'X-RapidAPI-Host': HOST },
    });
    res.writeHead(upstream.status, {
      'content-type': 'application/json',
      // A reload within 15 seconds is answered by the browser, not by your quota.
      'cache-control': 'public, max-age=15',
    });
    return res.end(await upstream.text());
  }
  res.writeHead(200, { 'content-type': 'text/html' });
  res.end(await readFile('index.html'));
}).listen(3000);

The page

<!doctype html>
<ul id="board"></ul>
<script>
const board = document.getElementById('board');

const periodLabel = (g) => {
  if (g.status === 'halftime') return 'Half';
  if (g.period <= 4) return 'Q' + g.period;
  return g.period === 5 ? 'OT' : 'OT' + (g.period - 4);
};

const render = (games) => {
  if (games.length === 0) {
    board.innerHTML = '<li>No games in play</li>';
    return;
  }
  board.innerHTML = games.map((g) =>
    '<li>' +
      '<img src="' + g.awayTeam.logoUrl + '" width="20" height="20" alt=""> ' +
      g.awayTeam.code + ' ' + g.score.away + ' - ' + g.score.home + ' ' + g.homeTeam.code +
      ' <img src="' + g.homeTeam.logoUrl + '" width="20" height="20" alt="">' +
      ' <small>' + periodLabel(g) + (g.clock ? ' ' + g.clock : '') + '</small>' +
    '</li>'
  ).join('');
};

const tick = async () => {
  try {
    const res = await fetch('/api/live');
    if (!res.ok) return;               // keep the last good board on screen
    render((await res.json()).data);
  } catch { /* offline: leave what is there */ }
};

tick();
setInterval(tick, 30000);
</script>

American scoreboards put the away team first, which is why the line reads away, then home.

Three things that will happen in production

A request will fail. The code above leaves the previous scores on screen rather than blanking the board. A scoreboard that flashes empty on one failed poll looks broken when nothing is wrong.

Nothing will be live. Most of the day the array is empty. Treat it as a normal state with real copy, not as an error. /games/next gives you the next tip-off to show instead.

A game will end while someone is watching. A finished game drops out of /games/live on the next poll. To keep it on screen, hold your own list and mark an entry final when it disappears, rather than replacing the array each time.

Where to go next

Once a game is over, /games/{id} has the score by quarter and every player's line. That is the next article.

More

What's inside a box score

A field-by-field walk through a real game response, the 2026 NBA Finals clincher: the score by quarter, starters and bench, minutes, shooting splits and plus-minus.

Reading an NBA table: games behind, the play-in and ties

What winPct, gamesBehind and zone mean in a standings response, how half a game happens, and why Philadelphia finished above Orlando in 2025-26 on a worse point difference.

Every endpoint mentioned here is in the documentation, and every plan includes them all, the free one too.