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

How to build a soccer scouting tool

Create a reproducible shortlist from production and chance quality, then open player detail only when identity is resolved.

API coverage and endpoint overview: Explore the soccer API

Why this is hard

The hard part is identity, not ranking

A scout can sort a table in seconds. The engineering work is proving that two source rows describe the same person and refusing to guess when they do not.

  • Legal names, initials and display names vary by source.
  • Transfers can attach more than one club to a season row.
  • Minutes filters matter more than raw rank for small samples.
  • A null canonical id must disable drill-down rather than trigger a name guess.

Path 1 · recommended

Have your AI agent build it

Use MCP for coverage and match context, then the league leaderboards for the shortlist.

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

  • find_players

    Find canonical player IDs by name for use with player-stat tools.

  • get_player_stats

    Per-player career or per-season totals and per-game rates.

  • 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 scouting shortlist. Rank a supported league on xG, xA and minutes. Resolve player detail only when the identity match is unique and club-consistent; otherwise leave the profile link unavailable.

What the agent cannot reach

xG rows can lack canonical player ids. A successful name search is not sufficient evidence if more than one candidate is returned.

Path 2 · hand-coded

Build it yourself

Separate ranking from identity resolution so a useful board does not depend on an unsafe join.

  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

    Build the measurable shortlist

    Apply a season-appropriate minutes floor before comparing xG and xA. This 300-minute floor is deliberately lower while the 2026 season is still young.

    Scouting boardbash
    curl -s "https://api.bigballsdata.com/v1/leagues/laliga/xg-leaders?season=2026&stat=xg&min_minutes=300&limit=100" \
  -H "x-api-key: $BBS_API_KEY"
  3. 03

    Compare creation and finishing

    Use xA and non-penalty xG as separate dimensions rather than collapsing every role into goals.

    Shortlist dimensionstypescript
    const shortlist = leaders
  .filter((p) => (p.minutes ?? 0) >= 300)
  .map((p) => ({ name: p.player_name, xg: p.xg, xa: p.xa, npxg: p.npxg }));

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/leagues/:id/xg-leadersMinutes, goals, xG, xA, non-penalty xG and involvement fieldsCreates the measurable shortlist for supported big-five leagues. Read the xG field guide.Solo
GET/v1/playersCanonical player search resultsProvides identity candidates but not permission to guess among ambiguous results.Free
GET/v1/players/:id/club-formResolved per-club season productionAdds longitudinal context after identity is proven.Free
GET/v1/players/:id/rolling-statsRolling performance windowsAdds current-form context to a production scouting workflow.Solo

Pricing, honestly

Solo adds chance quality and the changing player view

Free can build a production shortlist. Solo adds supported xG dimensions, rolling form and richer player presentation for an evaluator-facing tool.

Free key

jsonjson
Season production leaders and resolved club form.

Solo

jsonjson
Supported xG dimensions, rolling statistics, projections and player headshots where served.
  • Keep identity confidence visible.
  • Use a minutes floor.
  • Never replace missing competition data with a different league.
See the full plan ladder →

More tutorials

Other build guides

Known gaps

Identity work still matters

Presentation matching is not a canonical merge.

  • Unresolved source aliases remain null.
  • Ambiguous names must stay unlinked.
  • A same-club unique match is safer than name-only matching but still should not rewrite canonical identity.

Questions

Can I scout every soccer league with xG?
No. The xG shortlist is limited to supported big-five leagues.
Can I join leaderboards by player name?
Use names for display, not as an unconditional identity key. Profile links require a stable resolved id.
Why filter by minutes?
Per-minute and expected metrics become misleading on tiny samples; a visible threshold keeps comparisons defensible.

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 shortlist

Rank measurable performance first, then enrich only the identities you can prove.