Soccer extensions

Soccer extensions preserve additional source observations through separate endpoints across the 39 supported competition routes. Field availability depends on competition, match, season and source response. Route support does not establish complete data coverage or full STATS parity. Existing endpoints retain their response shapes, IDs, season handling, calculations and caches.

Read an extension

Use an existing canonical match ID with /v1/epl/games/{id}/extended?season_label=2025-2026&season_scope=split. The response uses the usual data / _meta envelope. The extension’s data contains provider stat sections, player metrics, events, lineup evidence and available match context. /players/{id}/extended, /teams/{id}/extended and /standings/extended expose separately stored subject observations when populated.

The numeric season is optional. Exact season_label and season_scope must be supplied together. Supported scopes are split, calendar, edition and transition. A label such as 2025-2026 is matched exactly. Calendar 2026, a tournament edition, J.League’s 2026 transition and its 2026-2027 split are distinct. Omitted entity selectors return the newest stored season/observation and disclose its scope. A missing extension returns unavailable.

All extension routes require the existing stats entitlement. They use Cache-Control: private, no-store and bypass the legacy cache.

/matches/{id}/extended is the soccer match alias. /venues/{id}/extended and /competitions/{id}/extended expose verified source observations for existing canonical subjects when populated; absent fields remain conditional. Optional stage matches an exact stored source label. Omission explicitly selects all stored stages inside the requested competition and season. Derived as_of is the latest contributing observation, not proof of a synchronized or complete final dataset.

Discover actual metric definitions

/v1/{league}/stat-definitions reads all matching stored extensions and returns observed source keys, raw labels, units, type metadata, periods, groups and exact counts. Use the same season selectors to restrict the observed set. An empty result means no definitions have been observed in that set; it does not prove that the source lacks the metric.

record_count counts matching documents containing a definition. observation_count includes separate home/away values within a source context. Numeric, nonnumeric and missing value counts distinguish a real zero from text or unavailable data. Source counts are observed counts, not season coverage percentages. coverage: null means not measured.

Team statistics preserve period_label and group_label. Player entries preserve type_id, label, raw value, numeric value and source metadata. Source percentages use 0–100 units, while numerator/denominator remain separate. Similar names do not establish the same definition as STATS or another provider. The existing dynamic metric surface also means an undocumented workbook field is not automatically missing data.

Player season and career views

/v1/{league}/players/{id}/season-stats/extended requires exact season_label and season_scope. It scans all stored final game extensions without the legacy 120-match cap. Its verified Flashscore count allowlist includes goals, assists, minutes, attempted/completed passes, attempted/on-target shots, yellow/red cards and saves, with separate team splits. Explicit raw count_value stays separate from a composite display percentage. Ratings and percentages are not added. Actual participation requires explicit evidence; zero statistics and rounded zero-minute entries do not establish DNP.

observed_totals shows available inputs. totals requires complete inputs within the observed appearances and a source final snapshot. Read participation_unknown, metric_observations, source_snapshot_unverified and unavailable_required_fields. Unrelated games without the player do not become unknown participation. Unknown team identities and duplicate player records remain visible. Extra time retains the source full-match scope; shootout goals are not inferred. complete remains false and coverage null until a schedule denominator is independently measured. These are observations, not certified full-season totals or qualification results.

/v1/{league}/players/{id}/career-stats/extended exposes independent stored provider career rows. Filter with exact source_season=2025/2026 or competition_name. These shared rows can include other competitions and clubs outside supported leagues. They are not restricted to the URL league, combined into totals or matched by a guessed competition name. The source competition label and provenance remain visible; canonical competition identity is unknown. Existing career and season endpoints keep their limits and behavior.

Source and coordinate limits

Player starts and substitute appearances require explicit starter flags in final snapshots. Goals/assists per game use actual appearances; per-90 values use verified total minutes and stay null for missing or zero denominators. Unused-bench counts remain unavailable without explicit nonparticipation evidence. Team /season-stats/extended and /head-to-head/extended?team_id=...&opponent_id=... use observed final goals only when their score scope excludes shootouts. Official points adjustments and knockout advancement rules are not inferred.

/leaders/extended accepts subject_type=player or subject_type=team and a compatible metric. It ranks only observed subjects with complete metric inputs, reports excluded subjects and counts all exact ties before applying limit. qualified stays null and complete false. These ranks describe the observed sample, not a certified full league leaderboard.

Provider incident roles, reasons and explicit wallclocks remain source evidence. Event minute is not wallclock. Repeated incident IDs can be revisions. Unknown officials, VAR classifications, cancellation times or substitution reasons remain unavailable. Formation grid coordinates are not average player positions. A passing matrix reports player-pair counts, not per-pass start/end coordinates. Momentum is not possession. Squad membership dates are not contract dates.

Official FIFA World Cup 2026 report fixtures verify passing-network, physical and specialist tables for specific matches. Report network totals differ from general completed-pass totals. Their definitions, units and source scope must remain explicit. UEFA 2025–26 passing-matrix reports are a source research lead; they do not establish implemented all-match coverage. Continuous tracking coverage across all 39 competitions is not established.

Extensions and source fixtures do not certify production or two-season coverage. Null fields and coverage remain visible until measured.

Pass completion and shots-on-target ratios divide complete summed counts and use fraction units. They never average source percentages. Missing/zero denominators or inconsistent numerator/denominator inputs return null. Count rates per game and per 90 minutes require actual observed appearances and minutes.

Populated official reports are available under data.official_reports.fifa_pmsr; optionally select report_source=fifa_pmsr on a match extension. They preserve the report URL, SHA-256, reviewed binding and template version, directed network matrix, distribution/offers/defending tables and physical metrics. Visible numeric zeros differ from blank matrix diagonals. Distances use metres and top speed uses km/h. FIFA sprint counts use zones 4+5 (20+ km/h), and cannot be compared directly with another provider’s threshold. The source-reported matrix covers its published network rather than every completed pass, and supplies no event sequence or per-pass coordinates.