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.

  1. 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"
  2. 02

    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"
  3. 03

    Load all typed incidents

    Request all event types, then sort by period and minute while preserving stable event identity for corrections.

    Match eventsbash
    curl -s "https://api.bigballsdata.com/v1/matches/$MATCH_ID/events?sport=football&type=all" \
  -H "x-api-key: $BBS_API_KEY"
  4. 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.

MethodPathReturnsWhy you need itPlan
GET/v1/matches/:idAuthoritative match identity, status, score and clock fieldsOwns the current state displayed at the top of the match center.Free
GET/v1/matches/:id/eventsTyped goals, cards, substitutions and VAR-style incidents when servedExplains the match state as a compact timeline.The product ladder intends play-by-play for Pro, but this shared soccer event route is not yet gateway-gated. Treat that enforcement mismatch as an open platform gap.Free

Pricing, honestly

Prototype now; plan for the Pro event floor

The current route serves event incidents without the intended Pro gate. The commercial ladder places play-by-play at Pro, so production packaging must not depend on today’s permissive enforcement.

Free key

jsonjson
Match state and the currently permissive event response.

Solo

jsonjson
The intended Pro product: live event access with the commercial floor enforced consistently.
  • Do not advertise full pass-by-pass coverage.
  • Keep the match score authoritative.
  • Track the known entitlement mismatch before launch.
See the full plan ladder →

More tutorials

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 product ladder places play-by-play at Pro. The shared event route is still permissive today, which is a known gateway enforcement gap.

Related APIs

Other APIs you can build with:

Premier League API: Scores & StatsSoccer API: Scores, Odds & StatsFootball API: Scores, Odds & StatsUEFA Nations League APIEuro Championship APICopa América API

How we compare

vs API-Sportsvs The Odds APIvs SportsData.io

Also on this sport

Premier League Injury APIInjury Data API for Developers: Free

Build the match center

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