CFDB

Get the current-season standings table. For a single-table competition (e.g. Primera División), returns 'table' — all teams, ranked, plus 'fixtures_remaining' (how many of this table's own matches are scheduled but not yet finished). For a competition split into groups (e.g. Copa Chile's group stage), a flat combined table would be meaningless (teams in different groups never played each other), so instead: pass 'team_name' to get just that team's own group as 'table' (plus 'group_name' and 'group_fixtures_remaining'), or omit 'team_name' to get every group's table at once under 'groups' (a dict keyed by group name, e.g. 'Group A') plus a parallel 'group_fixtures_remaining' dict (same keys) instead of 'table'. A remaining count of 0 does NOT by itself mean that group/table's phase has concluded — it only means CFDB has no more of its matches loaded yet; never infer 'this group is over' or 'team X has qualified' from played reaching some expected total, check this field or the next round via match.search/team.fixture instead. Requires 'league_name'.

league.standings

Get the full pre-match dossier for one match: everything match.preview returns, plus head-to-head history between the two teams and competition context (stage/final vs. regular season). Requires 'fixture_id'.

match.dossier

Get the full events timeline for one match, ordered by minute: goals (including penalties/own goals), cards, and substitutions, each with the player, minute, event type, and which side (home/away) it belongs to. Requires 'fixture_id'.

match.events

Get one match's lineups: for each team, 'starting_xi' and 'substitutes', each player with id, name, general position (their usual position, not necessarily what they played specifically in this match), is_captain, rating, and minutes_played. Two real limits, never guessed around: there is no tactical formation (e.g. '4-3-3') anywhere in CFDB because it isn't stored — and no per-match jersey number (only each player's current squad number exists, via team.squad, which may differ from what they wore in an older match); neither field is in this response at all. Both lists empty means lineup data hasn't been loaded for this match (only recently-finished live-schema matches get lineups fetched), not that the match had no lineup. Requires 'fixture_id'.

match.lineups

Get a knowledge-synthesis preview for one upcoming match: facts, recent form for both teams, current league standing, 'context.{home,away}_next_opponent_after_this_match' and 'context.{home,away}_previous_opponent_before_this_match' — each team's neighboring fixture relative to THIS match specifically, not necessarily the team's real current next/previous match (if asking 'what's Colo-Colo's next match' as of right now, use team.fixture(when='next') instead — these two fields answer 'who did/will they play around the time of this specific match'), rule-derived insights (win/loss streaks, table position), and 'press_context' — up to 2 press-sourced notes (stakes, injuries, narrative context) from distinct outlets when available (empty list otherwise; only populated within a few days of the match once the offline press loader has run). CFDB has no dedicated injury-tracking tool or field — injury mentions, when present at all, are incidental content inside these press notes. An empty or missing 'press_context' means no press coverage was loaded for this match (injuries or otherwise) — never read it as 'no injuries'; say coverage isn't available rather than implying a clean bill of health. Each press_context entry has 'scraped_at' (when CFDB captured it — always present) and 'published_at' (the article's own date, often null). Standings/points/goal-count figures mentioned inside a press note's narrative_context are a snapshot from that capture time, not live — this tool's own 'facts'/standings fields (and league.standings/player.top_scorers directly) are always more current; prefer those over a number quoted in press narrative when they disagree. 'context.pre_match_streak' gives each team's win/loss streak going INTO this match ({'home': {...}, 'away': {...}}, each {'type': 'W'|'L'|'D'|null, 'length': int}) — explicitly pre-match; match.report exposes the corresponding 'post_match_streak' for a finished fixture, and the two must never be confused. All kickoff times are Chile local time (America/Santiago). Requires 'fixture_id'.

match.preview

Get a post-match recap for one finished match: result headline, everything match.dossier returns, plus 'events' — the full goals/cards/substitutions timeline (same shape as match.events, no separate call needed), 'player_ratings' — every player from BOTH teams who has a real match rating on file, already sorted highest-to-lowest, each entry {player_id, name, team_id, team_name, rating, goals, assists} (goals/assists counted from this same match's real events); empty list if no player in the match has a rating loaded yet. Use this one field for every 'destacado'/'figura'/rating-related question about this match instead of calling player.match_stats per-player: for the overall standout, take player_ratings[0]; for one team's standout ('la figura de la U'), filter to that team_id first, then take its first entry — if that filtered list is empty, say that team has no rating data for this match rather than guessing one from the goal timeline, even when the other team's entries exist; for a top-N ranking, take the first N entries (per team or overall, matching what was asked); for 'quién rindió peor', take the last entry (again per team if asked that way). And 'press_context' — up to 2 press-sourced notes (reactions, incidents, why the result happened) from distinct outlets when available (empty list otherwise; only populated within a day of the match once the offline post-match press loader has run), each with 'scraped_at' (when CFDB captured it). 'context.post_match_streak' gives each team's REAL win/loss streak AFTER this match ({'home': {...}, 'away': {...}}, each {'type': 'W'|'L'|'D'|null, 'length': int}) — this match's own result is already folded in, so a loss correctly shows type='L', even if the team arrived on a long win streak (that pre-match streak is still available separately as 'context.pre_match_streak', inherited from match.dossier, but never use it to describe the team's CURRENT streak in a report — only post_match_streak is current after the final whistle). Same caution applies to 'context.{home,away}_next_opponent_after_this_match' (inherited from match.dossier) when reporting on an OLD match: it names the team's next fixture after THAT specific match, which by the time you're reading the report may already be in the past too — never read it as 'their next match as of today'; use team.fixture(when='next') for that. Fails with reason 'not_finished' if the match hasn't been played yet. Requires 'fixture_id'.

match.report

Scan one matchday for narrative angles: win/loss streaks (3+ games), winless streaks (5+ games without a win, includes draws), relegation-zone teams (bottom 2 of the current table — a simple proxy based on this season's table only, NOT Chile's official 3-season rolling-average relegation calculation, which CFDB does not compute), teams ≥10 points off the league leader, and goal-scoring milestones (a player reaching a multiple of 5 season goals — only surfaced for 'previous' matchdays, since future matches have no goals yet). Requires 'when' ('upcoming' or 'previous'); 'league_name' is optional.

match.storylines

Get results or the schedule for one matchday of a league. Kickoff times are Chile local time (America/Santiago). Requires 'when' ('upcoming' or 'previous'); 'league_name' is optional. Each team's 'streak' includes that team's own result in this match when the match is finished (when='previous'); for a scheduled match (when='upcoming') there's no result yet, so 'streak' is the streak going into the match instead. Each match's 'status' is 'scheduled', 'live', 'finished', 'postponed', 'cancelled', or 'unknown' — no in-play minute/clock is available.

match.matchday_results

Get a player's suspension risk from accumulated yellow cards this season (4 = risk, 5 = automatic suspension per Chilean football rules; no reset-after-serving logic), scoped to a single competition — suspension accumulation is per-competition, never blended. If the player has current-season appearances in more than one competition (league, cup, etc.) and no 'league_name' is given, returns a 'competition_required' error listing 'available_competitions' instead of guessing which one; retry with 'league_name' set to one of those. Requires 'player_name'.

player.status

Get one player's performance in one specific match (not a season average — use player.season_stats for that): is_starter, minutes_played, is_captain, and a curated set of match stats (rating, passes, accurate_passes, key_passes, shots_total, shots_on_target, tackles, interceptions, duels_won, successful_dribbles, fouls, saves, goals_conceded). Does NOT include goals/assists/yellow_cards for this match — use match.events for those. Any stat field can be null if the underlying data feed didn't record it for that match — never assume 0. Fails with reason 'not_found' if the player has no recorded appearance in that fixture. Requires 'fixture_id' and 'player_id' (get player ids from match.events or team.squad).

player.match_stats

Get a player's current-season stats (matches played, minutes, goals, assists, cards). Assists are inferred from goal-event data and may undercount. Also includes 'advanced_stats' — a curated set of season stats (rating, accurate_passes_percentage, key_passes, shots_total, shots_on_target, big_chances_created, tackles, interceptions, duels_won, successful_dribbles, fouls, saves, goals_conceded), or null when not yet migrated for this player+competition, or null when the player has current-season advanced stats in more than one competition (e.g. league + cup) and no 'league_name' was given — in that case, 'advanced_stats_available_leagues' lists which competitions have data, so you can retry with 'league_name'. Any individual advanced_stats field can itself be null if the underlying data feed never recorded it — never assume 0. Requires 'player_name'; optional 'league_name' to narrow scope.

player.season_stats

Get a season player ranking by a single stat: 'goals', 'assists', 'rating', 'accurate_passes_percentage', 'duels_won', or 'tackles'. Requires 'stat'. Optional 'league_name' (defaults to the server's default league); two independent, combinable position filters -- 'position_group' (coarse: 'GK'/'DEF'/'MID'/'FWD') and 'position' (exact: e.g. 'Left Back', 'Central Midfield' -- use this one for a specific role like 'left-backs' or 'wingers', not just position_group's broad DEF/MID/FWD split); use either alone or both together (AND). Both have real, partial coverage -- a filtered ranking may come back shorter than top_n or empty, which reflects real data coverage, not a missing feature, never fill the gap with a guess. Also 'seasons_back' (0=current season, up to 2 seasons back), 'top_n' (default 10, max 10). 'rating' and 'accurate_passes_percentage' exclude players under 450 minutes played that season and return an 'insufficient_sample' error if nobody clears that floor; the other stats have no floor. Every row includes 'matches_played' and both 'position_group'/'position' regardless of which stat or filter was requested.

player.stat_leaders

Get CFDB's own team power ranking for a league (CFDB's original methodology: 40% points/game + 35% goal difference/game + 25% recent form). For a competition split into groups (e.g. Copa Chile's group stage), a single cross-group score would be meaningless — teams in different groups haven't played comparable schedules — so the response is a 'groups' dict (each group's own independently-normalized ranking) instead of one flat 'ranking' list; check which key is present. An empty 'ranking' includes an explicit 'reason' ('no_standings_data') and 'message' — never read a bare empty list as evidence the competition doesn't exist. Requires 'league_name'.

league.power_rankings

Search for matches by date (exact or range), team(s), competition, and/or exact season label — all filters are combinable, at least one is required. Transparently searches both CFDB's historical archive (1933-2023) and live data (2024-present) in one call — the caller never needs to know which source a given date falls into. This tool itself never returns goalscorers for either era — for goal-by-goal detail, chain into match.events/match.report (only for 'live' rows, using their fixture_id) or historical.matches (for 'historical' rows, using the result's competition_name/season_label — historical goal detail is per-season, not looked up per match; it exists for many but not all loaded matches, empty means not loaded, never assume a historical match has no recorded scorers just because fixture_id is null here). Each result is tagged 'source': 'historical' or 'live'; 'fixture_id' is null for historical rows. Every result also has 'status' ('scheduled', 'live', 'finished', 'postponed', 'cancelled', or 'unknown' — historical rows are always 'finished'); a 'scheduled' match's 'home_score'/'away_score' are always null, never a placeholder 0-0 — the match hasn't been played yet. There is no in-play minute/clock available (CFDB doesn't poll live match state at that granularity), so 'live' only means the match has started and isn't finished, nothing more precise. Results are paginated with 'limit' (default 50, max 200) and 'offset' (default 0); 'total_found', 'has_more', and 'truncated' make omitted rows explicit. Complements, not a replacement for, team.fixture/match.matchday_results/historical.matches/team.h2h, which stay better suited to their specific use cases.

match.search

Get a team's next or last match, with the full fixture detail already included — no follow-up call needed. Kickoff time is Chile local time (America/Santiago). Each team's 'streak' includes that team's own result in this match when it's finished ('when'='last'); for a scheduled match ('when'='next') there's no result yet, so 'streak' is the streak going into the match instead. 'status' is 'scheduled', 'live', 'finished', 'postponed', 'cancelled', or 'unknown' — no in-play minute/clock is available. Requires 'team_name' and 'when' ('next' or 'last').

team.fixture

Get one team's stat profile in one specific match: a curated set of match stats (possession_percentage, successful_passes_percentage, shots_total, shots_on_target, corners, fouls, tackles, duels_won, interceptions, big_chances_created). This is the team-level counterpart to player.match_stats. Does NOT include goals (use match.matchday_results/team.fixture for the score) or cards (use match.events). Any stat field can be null if the underlying data feed didn't record it for that match — never assume 0. Fails with reason 'not_found' if no stats are recorded for that team in that fixture. Requires 'fixture_id' and 'team_id'.

team.match_stats

Get a team's profile: current coach (null if none on file), 'rivals' (all historic rivals on file, deterministically ordered, possibly empty), legacy singular 'rival' (populated only when exactly one rival is on file; null when there are none or several, because CFDB does not guess which is primary), 'founded' — the team's founding year, null until manually loaded for that team (no automated feed provides this; a small, curated set of teams have it, not all), and 'external_profile' — stadium name, stadium city, and a short narrative bio, all sourced from a single Wikipedia article per team and manually curated (never auto-refreshed), or null when not yet loaded for that team. Requires 'team_name'.

team.profile

Get a team's recent form (last N finished matches, default 5) and current win/loss streak. Kickoff times are Chile local time (America/Santiago). Requires 'team_name'.

team.form

Get a team's squad for one specific season/year — 'team_name' is matched case/accent-insensitively; 'season_label' must still match exactly (e.g. '2000', 'Apertura 2002' — check historical.season_summary for the exact label). Coverage is partial: only the current canonical season is auto-populated (from live squad membership); every other season, historical or canonical, returns an empty roster until it has been loaded by hand. An empty roster means 'not loaded yet', not 'no players'.

team.season_roster

Get a team's current roster: each player's id, name, position (may be null when not on file), 'joined_at' (may be null — not always on file), and 'last_seen_at' — the date of that player's most recent match appearance for this specific team, so you can judge how current the listing actually is for that player (a player last seen a while ago may be injured/out of favor rather than genuinely gone). Membership is auto-derived from match appearances and excludes anyone with no appearance for the team in the last ~200 days — not a live, minute-by-minute transfer feed. Requires 'team_name'.

team.squad

Get a team's current position in its league table (points, played, wins/draws/losses, goal difference, position). For a competition split into groups (e.g. Copa Chile's group stage), position/total_teams are scoped to the team's own group, not the whole competition, and a 'group_name' field is included. Requires 'team_name'; optional 'league_name' to disambiguate a team that plays in more than one current competition. 'group_fixtures_remaining' is how many of this team's own group/table matches are scheduled but not yet finished — 0 does NOT necessarily mean the group/season has concluded, only that CFDB has no more of its matches loaded yet; never assume 'group is over' or 'team has qualified' from played==total_teams-based math alone, check this field (or call match.search/team.fixture for the next round) instead.

team.standing

Get a season team ranking by a single stat: 'possession_percentage', 'successful_passes_percentage', 'shots_total', 'duels_won', 'tackles', or 'big_chances_created'. Requires 'stat'. Optional 'league_name' (defaults to the server's default league), 'seasons_back' (0=current season, up to 2 seasons back), 'top_n' (default 10, max 10). Only counts finished matches. 'possession_percentage' and 'successful_passes_percentage' are per-match averages and exclude teams under 3 finished matches that season (returns 'insufficient_sample' if nobody clears that floor); the other stats are season totals with no floor.

team.stat_leaders

Get how many times a team has won a competition, blending CFDB's historical records with finished current-schema seasons (same table-based-competition scope as league.champion_history). 'league_name' is optional — a question like 'how many titles does X have' is ambiguous in scope (one competition vs. every official title), so omitting 'league_name' returns 'total_official_titles' plus an 'included_competitions' list naming exactly which competitions that total covers (Primera División, Copa Chile, Supercopa, Copa de la Liga — NOT Liguilla Pre-Libertadores/Pre-Sudamericana, which have their own real titles via league_name='Liguilla Pre-Libertadores' but aren't summed into this total) plus a 'by_competition' breakdown, instead of silently picking one competition or implying a grand total across every title CFDB knows about. Pass 'league_name' only when the user actually specified a competition. 'team_name' accepts common nicknames/abbreviations ('la U', 'el Cacique', 'U de Chile') via the same alias resolution team.fixture uses; an unresolved or misspelled name returns a not_found error, never a false '0 titles'. Requires 'team_name'.

team.title_count

Get a league's current-season top scorer ranking: rank, player (id + name), team (id + name), and goal count, sorted descending. Requires 'league_name'; optional 'top_n' (default 10).

player.top_scorers

Get a coach's profile: current team (null if not currently coaching any team on file or if multiple current-team records are equally plausible), 'current_team_candidates' (the unresolved candidates in that ambiguous case; empty otherwise), tenure start date, previous teams, date_of_birth and nationality (both null until the offline coach profile loader has resolved this coach), 'press_context' — up to 2 press-sourced notes on career trajectory/tactical style from distinct outlets when available (empty list otherwise; populated for coaches who were active when the offline coach press loader last ran — a one-shot, non-refreshing load), and 'external_profile' — full name, place of birth, height (cm), preferred foot, an external profile link, and club career history (always empty for now, the current profile source doesn't expose transfer history), or null when no confident match was found (resolved by an exact name match against the external profile source; if more than one coach shares that name, narrowed by current club membership; ambiguous matches are skipped, never guessed; only populated once the offline coach profile loader has run for this coach). Requires 'coach_name'.

Get a player's basic profile: position, nationality, date of birth, and current team (team_id + name). Position/date_of_birth return null when not on file — never fabricated. Also includes 'external_profile' — full name, place of birth, height (cm), preferred foot, an external profile link, and club career history (populated only for players loaded before this pipeline switched sources — always empty for newly processed profiles because the current profile source doesn't expose transfer history), or null when no confident match was found (resolved by an exact name match against the external profile source; if more than one player shares that name, narrowed by current club membership; ambiguous matches are skipped, never guessed; only populated once the offline player profile loader has run for this player). Requires 'player_name'.