Docs · foot.io

§01quickstart5 min

Quickstart.

Three lines.

# 1. install the sdk (or skip — curl works fine)
npm i @footio/client

# 2. drop your key in your env
export FOOTIO_KEY=fk_live_xxxxxxxxxxxx

# 3. query
curl https://api.foot.io/v1/players?name=ilike.*xhaka* \
  -H "x-api-key: $FOOTIO_KEY"
        

That returns Granit Xhaka's full profile JSON — biographics, current club, contract, all 8 external IDs. Same shape for any player. The same pattern (predicate filtering, embedding) works on every resource.

§02authenticationx-api-key

Authentication.

Public reads work without a key (rate-limited per-IP). Authenticated reads use x-api-key header.

# in any request:
-H "x-api-key: fk_live_xxxxxxxxxxxx"

Free tier: 5,000 req/month. Pro: 250k. Commercial: unlimited. Keys can be scoped (read-only, write-allowed for auth flows, etc.) and can be revoked from the dashboard.

§03filteringpostgrest-style

Filtering.

Operators on every column. Same pattern Postgrest uses.

Operator	Meaning	Example
`eq`	equal	`?country=eq.IT`
`gt / gte / lt / lte`	compare	`?height_cm=gte.190`
`in`	any of	`?position=in.(GK,DF)`
`like / ilike`	SQL LIKE	`?name=ilike.haaland`
`not.eq`	negation	`?retired=not.eq.true`
`or / and`	compose	`?or=(goals.gte.20,assists.gte.15)`
`order`	sort	`?order=goals.desc,name.asc`

§04embedding?select=…

Embedding.

Pull related rows in one request.

curl 'https://api.foot.io/v1/matches
  ?season_id=eq.471
  &select=match_date,home_score,away_score,
    home:teams(name,logo_url),
    away:teams(name,logo_url),
    venue:stadiums(name,capacity),
    events:match_events(minute,event_type,player:players(name))'

One round-trip. Embedding follows foreign keys. Use the alias syntax (home:teams!matches_home_team_id_fkey) when there are multiple FKs to the same table.

§05pagination & limitsRange header

Pagination & limits.

Either ?limit=50&offset=100 or HTTP Range header (Range: 0-99). Default page size 100, max 1000. Use Prefer: count=exact to get total count in the Content-Range header.

§06players/v1/players

Players.

412k profiles. Same schema for every player.

GET/v1/players

List players with filters.

Field	Type	Description
id	int	Internal player ID.
name	text	Display name.
date_of_birth	date	YYYY-MM-DD.
country_id	int	FK → countries.
position	enum	GK \| DF \| MF \| FW.
detailed_position	enum	CB, RB, DM, AM, RW, ST, etc.
height_cm	int	Height in cm.
preferred_foot	enum	L \| R \| Both.
external_ids	jsonb	Cross-reference IDs (Wikidata + other public ID systems).

GET/v1/players/:id/season_stats

Career season-by-season stats.

GET/v1/players/:id/shots

Per-shot xG with xy coordinates back to 2018-19 (Big-5) and 2020-21 (rest).

§MCPllm-native interfacestdio + http

MCP server.

Anthropic's Model Context Protocol means LLMs (Claude, GPT-4, local models) can query foot.io in natural language without you writing the queries.

# claude mcp add footio https://api.foot.io/mcp \
#   --transport http --bearer $FOOTIO_KEY

# now Claude can answer:
#   "Which French ref booked Pogba most often?"
#   "Compare De Bruyne and Modric's progressive passes per 90 since 2018."
#   "Get me the all-time top scorers in Liga MX before 1990."

The MCP server exposes 12 high-level tools (search_players, list_matches, get_table, …) that compose the underlying REST. The LLM picks the right tool, gets typed results, and synthesises an answer.

§hookpush notificationsPOST /v1/webhooks

Webhooks (Pro+).

We POST to your endpoint when something interesting happens. Events: transfer.completed, match.kicked_off, match.finished, injury.reported, card.shown, goal.scored.

curl -X POST https://api.foot.io/v1/webhooks \
  -H "x-api-key: $FOOTIO_KEY" \
  -d '{"url": "https://your.app/foot-hook",
       "events": ["transfer.completed"],
       "filter": {"club_id": 55}}'

One API.One schema.