Data Model · SoccersAPI docs

Entities and how they link

Competition tree from continent to match, and the entities linked from a match

From	Field	Leads to
League (`leagues?t=info`)	`seasons[].id`, `id_current_season`, `id_current_stage`, `id_current_round`	Season, stage and round to query next.
Season (`seasons?t=info`)	`league_id`, `stages[]`, `round_ids[]`, `current_round_id`, `current_stage_id`, `start`, `end`	Stages carry `has_standings` and `has_cupdraw`; rounds are the match days.
Match	`league.id`, `season_id`, `stage_id`, `group_id`, `round_id`, `teams.home.id`, `teams.away.id`, `venue_id`, `referee_id`, `teams.*.coach_id`, `aggregate_id`, `related_id`	Every other resource of the match.
Team (`teams?t=info`)	`current_seasons[]`, `leagues[].current_season_id`, `coach_id`, `venue_id`	Seasons to query for fixtures and standings.
Player (`players?t=info`)	`team_id`, `national_team_id`, `roles[].team.id`, `leagues[].seasons[]`	Current and past teams and competitions.
Broadcast	`tvs[].id`, `broadcast[].id`	Channel profile (`broadcast?t=info`) and its fixtures (`fixtures?t=tv`).

Seasons are the pivot of the model: fixtures, standings, teams, leaders and season statistics are all keyed by season_id. A league profile gives you the current one; seasons[] on the same profile gives you the history, newest first.

Identifiers

IDs are stable and unique per entity type. Reuse them across routes: a team_id from a match is the id for teams?t=info.
The same ID can be serialised as a number or as a numeric string depending on the operation ("id": 20 in a match, "team_id": "20" in its events). Compare them as strings or normalise before strict comparisons.
Flags follow the same rule: is_cup, is_current or deleted arrive as "0"/"1", 0/1 or true/false depending on the object.
common_name is the short display name (Bayern Munich), name the full one (FC Bayern Munich), short_code the three-letter code (BMU).

Images

Image fields contain CDN URLs. For routes that include a size segment, replace that segment with 18, 50, 80, 100 or 150 to request the same asset at another supported size. See Images & CDN for the full pattern table, working examples and fallback guidance.

Dates and times

Match times live in time: datetime, date and time are strings in the offset selected with utc (the offset is echoed in time.timezone, for example UTC+2); timestamp is the Unix kickoff time and never changes with utc. Store the timestamp and format it client-side.
time.minute is the match clock while the match is in play and null otherwise; status_period tells the half.
Search results carry startdate as YYYY-MM-DD HH:MM:SS, also shifted by utc. Odds carry last_update.date with its own timezone (UTC).
Dates you send (d) are YYYY-MM-DD; anything else answers 400.

Colours

teams?t=info returns kit[] with the home, away, third and goalkeeper kits, each with hex colours for shirt, sleeve, number and, where present, sleeve_detail. Matches embed the colours of the kit each side wears in teams.home.kit_colors and teams.away.kit_colors.

Coverage

Coverage differs by competition and by match. Read the flags before showing a tab: coverage.has_lineups, coverage.has_tvs and coverage.has_standings on a match, has_standings and has_cupdraw on a stage. A dataset that is not covered returns 200 with an empty array or null fields, never an error; see Plans and Data Access for what a 403 means instead.

Read in the reference