Recipes

Task-oriented guides. Each one states a goal, shows the exact sequence of calls, gives working code, and names the traps that are not visible from the reference alone.

Every code sample on these pages has been run against the production API - the payloads and values shown are real responses, not illustrations.

Start here

Recipe	What you get	Time
Get a token and make your first call	Credential exchange, token caching, first working request	5 min
Display a league table	The two-step navigation from stage to rendered table	10 min
Get one match with score and stats	Reading a score correctly, statistics, timeline	10 min
Show a match timeline	Ordering, deduplication, corrections, added time, substitutions	15 min
Build a livescore board	One polled endpoint, clock rendering, when to move to push	15 min
Display a knockout bracket	Rounds, nodes and slots into a renderable tree, two-legged ties	20 min
Sync incrementally instead of re-fetching	The timestamp cursor, why the boundary is inclusive	12 min
Show top scorers, cards and assists	19 ranking types, and why player rows invert participant	12 min
Compare two teams head to head	All-time balance, last 10, and the five-level event tree	8 min
List a team squad	Players, departed players and the coach in one array	8 min
Build a season calendar	A whole season of fixtures with scores, grouped by round	12 min

Concepts you need first

Four things are worth understanding before any recipe, because otherwise the sequences look arbitrary. They are covered inline in the recipes above and collected in the planning document:

• The payload is in api.data, not at the top level
• Match state needs three fields - status_type, status_id and relation_status. A postponed match still reports status_type: "scheduled"
• The clock is in seconds and resets each period. played_time is the cumulative total
• There is no score field - you select a result by id from results[]

Planned

Written but not yet published in full: squads and lineups, head-to-head comparison, browsing competitions by country, top scorers and cards. The full list with priorities is in docs/recipes.md.

Reference catalogues

Machine-readable catalogues harvested from the API, useful when interpreting payloads:

File	Contents
spec/reference/statuses.json	all 369 event statuses with id, name, type
spec/reference/incidents-by-sport.json	incident definitions for soccer, basketball, tennis, volleyball, ice hockey
spec/harvest/*.json	one real response per endpoint, redacted and trimmed