Build a live NBA scoreboard
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:
| Field | While in play |
|---|---|
status | live, or halftime during the break |
period | The quarter, 1 to 4, then 5 for the first overtime, 6 for the second |
clock | Time 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.