👨🎓Match Facts - beta
This is currently a beta feature. Please contact our support team if you're interested in joining the beta
Building a great football application requires more than just scores and statistics. Fans want context, insights that explain trends, highlight key players, and reveal the patterns behind what's happening on the pitch.
Match Facts delivers that context directly through the Sportmonks Football API.
Instead of retrieving large historical datasets, writing filtering logic, and maintaining calculation models yourself, Match Facts provides pre-calculated insights your application can surface instantly. Before kickoff and live during the match, through the same fixtures endpoint you're already calling.
What Match Facts does
Match Facts transforms historical and live match data into structured, ready-to-use insights. They cover seven categories:
Team & Match Statistics: scoring patterns, attacking activity, discipline trends, and match dynamics
Player-Based Facts: top scoring threats, standout performers, and player narratives built from recent form
Referee Insights: discipline tendencies and officiating patterns compared against league averages
Head-to-Head & Coach Facts: historical records between teams and managers, calculated automatically
Statistical Comparisons: how teams perform relative to league average, at home vs away, and across competitions
Match Context Facts: scheduling, recent match history, and situational factors surrounding the fixture
Streaks: winning runs, scoring streaks, clean sheet sequences, and disciplinary trends across consecutive matches
Window variations
Many Match Facts support window variations, the same insight calculated across different timeframes so your application can choose the most relevant context.
Available windows: last 5, last 10, last 15, last 25, and all-time.
Window variations are only generated when sufficient match history exists. If a team has played fewer matches than the window requires, that variation is not returned, preventing misleading statistics automatically, without any validation logic on your side.
Natural language insights
In addition to structured data, Match Facts can return natural language sentences ready to display directly in your application: no formatting logic required.
Example:
AI Overviews
For a limited time, Match Facts includes access to AI Overviews. Add the AIOverviews include to your fixtures call and receive a fully written, ready-to-display match summary generated directly from the underlying Match Facts data.
No prompt engineering. No model to maintain. No post-processing.
Endpoint:
Example output:
"VfB Stuttgart have enjoyed a dominant run against Borussia Dortmund, securing victory in their last 5 Bundesliga encounters. In those same 5 matches, Borussia Dortmund have failed to register a win. VfB Stuttgart have also been in strong recent league form, winning 6 of their last 7 Bundesliga fixtures. Meanwhile, Borussia Dortmund have a solid home record in the league, having won 8 of their last 10 matches at home."
How to access Match Facts
Match Facts are available as an add-on to the Sportmonks Football API. Access them by adding the matchfacts include to your existing fixtures endpoint call.
Same authentication. Same data format. No new infrastructure to learn.
Updated field structure
As of the 18-03-2026 release, the Match Facts response structure has been updated. Please review the following changes before integrating:
category
basis
Renamed. Possible values: team · global · h2h
team
participant
Renamed. Possible values: home · away · both · referee
—
category
New field. Possible values: statistics · statistic_comparison · players · coaches · referees · streaks
—
scope
New field. Possible values: all_matches · league_matches
Deprecated filter: The facts dynamic filter in the matchFactTypes endpoint has been deprecated. Replace with matchFactTypes: {IDs}.
What you can build
Match Facts are designed for any application that needs contextual football content:
Match previews: surface head-to-head history, form, and player narratives before kickoff
Automated commentary: trigger natural language insights from live in-match events
Fan engagement widgets: show streaks, scoring patterns, and momentum data in real time
Betting insights: goal line streaks, first-to-score patterns, and BTTS trends across window variations
AI-generated content: combine structured Match Facts with AI Overviews for editorial-quality match coverage at scale
Match Facts are calculated directly from the underlying Sportmonks datasets and served through the same production-grade infrastructure that powers our sports data worldwide. Every insight is validated automatically. Window variations are only generated when sufficient match history exists, so you never surface a misleading statistic.
You can also use the matchFacts include on one of our fixtures endpoint.
When you opt for the matchFacts include on one of the fixtures endpoint, you can also use the havingLiveMatchFacts filter. This filters fixtures that have live match facts, such as outcomes by players sent off field & outcomes by goals
Last updated
Was this helpful?