Does the feed include every pass?

No. It is a key-event feed for goals, cards, substitutions and VAR-style incidents.

Should I derive the score from goals?

No. Use the match response as the authoritative score and events as explanation.

What plan includes soccer play-by-play?

The full soccer minute-by-minute stream is included on Pro. The default scoring-event view remains available on Free.

Tutorial · 9 min · endpoints verified 2026-09-17

How to build a soccer live match center

Combine score, clock, teams and typed goals, cards, substitutions and VAR incidents without calling a key-event feed possession-by-possession commentary.

API coverage and endpoint overview: Explore the soccer API

Why this is hard

Live state and event history are different streams

A trustworthy match center keeps the score state authoritative and uses events to explain changes. Reconstructing the score only from events creates drift when an incident is corrected.

Poll or subscribe to match state independently from the timeline.
Events are typed incidents, not every pass or possession.
Late corrections must replace an event by identity rather than append a duplicate.
Mobile layouts need one readable column without horizontal scrolling.

Path 1 · recommended

Have your AI agent build it

MCP can resolve matches; use REST for the event timeline.

1. Connect the MCP server

Add the server in your MCP client and sign in with your Big Balls account. Your client registers itself and handles the token exchange — there is no key to copy.

MCP client configjson

{
  "mcpServers": {
    "bigballs-sports-data": {
      "url": "https://mcp.bigballsdata.com/mcp"
    }
  }
}

2. Tools your agent gets

get_matches
Live, upcoming or historical matches for a sport or league.
get_coverage
Machine-readable map of what we hold and what we do not.

3. Ask for what you want

Paste this at your agent. It is written to make the model check coverage before it designs anything, which is what stops it inventing a field we do not serve.

Prompttext

Build a soccer match center for a match id I provide. Show authoritative match score and status first, then fetch typed events and render goals, cards, substitutions and VAR in time order. Do not describe the event feed as every pass.

What the agent cannot reach

The MCP server has no match-event tool. Event availability is competition-specific, and the route currently does not provide completed passes.

Path 2 · hand-coded

Build it yourself

Make the match response the state source and the event response the narrative source.

01
Check the live coverage map first
Ask the coverage endpoint what is served before you make a field required in your interface. An unavailable field should produce an honest empty state, not a guessed value.
Verify soccer coveragebash
```
curl -s "https://api.bigballsdata.com/v1/coverage?sport=football" \
  -H "x-api-key: $BBS_API_KEY"
```

Load the match state

This response owns team identity, kickoff, status and score.

Match statebash

curl -s "https://api.bigballsdata.com/v1/matches/$MATCH_ID?sport=football" \
  -H "x-api-key: $BBS_API_KEY"

03
Load all typed incidents
On Pro, request all event types, then sort by period and minute while preserving stable event identity for corrections. On Free, omit type or use type=goals for the scoring summary.
Match eventsbash
```
curl -s "https://api.bigballsdata.com/v1/matches/$MATCH_ID/events?sport=football&type=all" \
  -H "x-api-key: $BBS_API_KEY"
```
04
Render a compact timeline
Map event type to a label and icon, but keep the server detail visible. The timeline should wrap on narrow screens rather than create a horizontal rail.
Timeline orderingtypescript
```
const timeline = [...events].sort((a, b) =>
  (a.period ?? 0) - (b.period ?? 0) || (a.minute ?? 0) - (b.minute ?? 0)
);
```

Reference

Every endpoint this tutorial uses

All on the gateway at api.bigballsdata.com. Verified against production on 2026-09-17.

Method	Path	Returns	Why you need it	Plan
GET	/v1/matches/:id	Authoritative match identity, status, score and clock fields	Owns the current state displayed at the top of the match center.	Free
GET	/v1/matches/:id/events	Free scoring events, or the full typed minute-by-minute stream on Pro	The default goals view is Free; use type=all on Pro for the complete minute-by-minute timeline.	Free

Pricing, honestly

Free scoring events; Pro minute-by-minute

Use the Free scoring summary for a compact match center. Upgrade to Pro for cards, substitutions, shots, VAR and the rest of the typed event timeline.

Free key

jsonjson

Match state plus the default scoring-event response.

Solo

jsonjson

The complete minute-by-minute event stream.

Do not advertise full pass-by-pass coverage.
Keep the match score authoritative.
Use type=all only when the key has Pro access.

See the full plan ladder →

Other build guides

Known gaps

What the event feed is not

The measured taxonomy defines the UI.

It is not completed-pass commentary.
It is not guaranteed for every soccer competition.
Event corrections need stable replacement semantics in the client.

Questions

Does the feed include every pass?: No. It is a key-event feed for goals, cards, substitutions and VAR-style incidents.
Should I derive the score from goals?: No. Use the match response as the authoritative score and events as explanation.
What plan includes soccer play-by-play?: The full soccer minute-by-minute stream is included on Pro. The default scoring-event view remains available on Free.

Related APIs

Other APIs you can build with:

Premier League API: Scores & Stats Soccer API — One Schema, Every Competition Football API — One Schema, Every Competition UEFA Nations League API Euro Championship API Copa América API

How we compare

vs API-Sports vs The Odds API vs SportsData.io

Also on this sport

Premier League Injury API Injury Data API for Developers: Free

Build the match center

Start from a real match id and keep every unavailable event state explicit.