/acquire

name: nutmeg-acquire
description: "Get football data: fetch, scrape or download from StatsBomb, Opta, FBref, Understat, SportMonks, Wyscout, Kaggle or any source, and set up API keys and access. Use when the user wants data, or asks what is free and what is paid."
argument-hint: "[what data to get]"
allowed-tools: ["Read", "Write", "Bash", "Glob", "Grep", "Agent", "AskUserQuestion", "mcp__plugin_nutmeg_football-docs__search_docs", "mcp__football-docs__search_docs", "mcp__plugin_nutmeg_football-docs__resolve_entity", "mcp__football-docs__resolve_entity"]

Acquire

Help the user get football data from any source into their local environment. This includes setting up credentials for providers that require them.

Accuracy

Read and follow `${CLAUDE_PLUGIN_ROOT}/docs/accuracy-guardrail.md` before answering any question about provider-specific facts (IDs, endpoints, schemas, coordinates, rate limits). Always use `search_docs` — never guess from training data.

First: check profile

Read `.nutmeg.user.md`. If it doesn't exist, continue with sensible defaults (Python and pandas) and suggest running `/nutmeg` setup at the end. Use the profile, when present, to determine preferred language and available providers.

Credentials

If the user needs to set up API keys or asks "what can I access for free?", handle it here.

**Key management rules:**

• Keys go in `.env` (gitignored), environment variables, or `.nutmeg.credentials.local` (gitignored)
• Never commit keys to git. Verify `.gitignore` includes `.env` and `*.local`
• Test the key works with a minimal API call
• Never print or log API keys

**Provider access reference:**

| Source | Access | Env var | |--------|--------|---------| | StatsBomb open data | GitHub / statsbombpy | — | | FBref | Web scraping (soccerdata) | — | | Understat | Web scraping (soccerdata) | — | | ClubElo | HTTP API | — | | football-data.co.uk | CSV download | — | | Transfermarkt | Web scraping | — | | SportMonks | REST API | `SPORTMONKS_API_TOKEN` | | Football-data.org | REST API | `FOOTBALL_DATA_API_KEY` | | FPL | Unofficial API | — | | Opta/Perform | Feed | `OPTA_FEED_TOKEN` | | StatsBomb API | REST API | `STATSBOMB_API_KEY`, `STATSBOMB_API_PASSWORD` | | Wyscout | REST API | `WYSCOUT_API_KEY` | | Kaggle | Download | — | | GitHub datasets | Download | — |

The env var names are nutmeg's conventions. Access terms, free tiers, coverage and rate limits change: before you tell the user what a source offers, check it with `search_docs(query="access coverage", provider="<provider>")` and name the doc you used.

Decision tree

When the user asks for data, determine the best source:

1. What data do they need?

| Need | Free options | Paid options | |------|-------------|-------------| | Match events (pass-by-pass) | StatsBomb open data | Opta, StatsBomb API, Wyscout | | Season stats (aggregates) | FBref, Understat | SportMonks, provider APIs | | xG / shot data | Understat, StatsBomb open data | Opta, StatsBomb API | | Tracking data (player positions) | Small open samples (for example SkillCorner open data, DFL/Sportec open data, Metrica sample data), loaded with kloppy | Second Spectrum, SkillCorner, TRACAB, Hawk-Eye | | Historical results | football-data.co.uk | SportMonks | | Elo ratings | ClubElo | - | | Player valuations | Transfermarkt (scraping) | - | | Cross-provider entity IDs | Reep Register (CC0 DuckDB/CSV release) | - |

Free sources change without notice. For example, FBref stopped serving its advanced statistics (xG, progressive actions and similar) in January 2026 (football-docs: `free-sources/fbref`). Before you recommend a source for a specific field, confirm with `search_docs` that the source still provides it, and say so if it does not.

2. Write acquisition code

Adapt to the user's language preference from `.nutmeg.user.md`.

**Python patterns:**

# StatsBomb open data
from statsbombpy import sb
events = sb.events(match_id=3788741)

# FBref via soccerdata
import soccerdata as sd
fbref = sd.FBref('ENG-Premier League', '2024')
stats = fbref.read_team_season_stats()

# Understat via soccerdata
understat = sd.Understat('ENG-Premier League', '2024')
shots = understat.read_shot_events()

**R patterns:**

# StatsBomb
library(StatsBombR)
events <- get.matchFree(Matches) %>% allclean()

worldfootballR, the usual R wrapper for FBref and Transfermarkt, is archived and no longer maintained. Check its status before you recommend it, and offer the Python route (soccerdata) or a direct download if it no longer works.

**JavaScript/TypeScript:**

// StatsBomb open data (direct from GitHub)
const resp = await fetch('https://raw.githubusercontent.com/statsbomb/open-data/master/data/events/{match_id}.json');
const events = await resp.json();

3. Data validation

After acquiring data, always:

• Check event counts are sensible. Typical counts depend on the provider (a provider that records carries and pressures has far more events per match), so compare each match with the other matches in the same dataset and flag outliers
• Verify key fields are present (coordinates, player IDs, timestamps)
• Check for missing data (some providers have gaps for certain competitions)
• Warn about coordinate system differences if combining sources
• Check for duplicated rows and repeated IDs (scrapers often double-count pages)
• Inside a research project, record each file's source with

`python3 "${CLAUDE_PLUGIN_ROOT}/core/nutmeg.py" data add <file> --source "<where it came from>" --licence "<if known>"`; it stores the hash and reports duplicates, repeated IDs and empty columns. Data from an unknown or unofficial source can be wrong or altered: say where it came from in the output, and check a few values against a second source when the numbers matter

Entity ID resolution

When joining data from different providers (e.g. FBref stats with Transfermarkt valuations), join through **Reep Register IDs**, not names.