Match Facts

Contents

What Sportmonks provides

Each Match Fact is a structured record tied to a specific fixture. It includes a category field that groups it by insight type, a team field indicating which side it applies to, a data object containing the underlying counts and percentages, and a natural_language field that renders the fact as a ready-to-display sentence, such as “Karbala has 2 wins against Newroz SC”.

The categories of facts currently available include:

– Head-to-head statistics covering total matches played between two teams, with wins, losses, and draws broken down by home and away.
– Scoring trends covering how frequently matches between these teams end with over 0.5, 1.5, or 2.5 goals, plus goal distribution insights.
– First-to-score patterns showing win, draw, and loss breakdowns based on which team scores first.
– Live match context covering outcome probabilities based on the current scoreline, and real-time facts triggered by in-match events such as yellow cards and red cards
– Momentum and situational data reflecting team performance in specific match situations

You can filter Match Facts down to specific fact types using the facts filter with the relevant type IDs.

Endpoints

There are four Match Facts endpoints:

GET All Available Match Facts returns every Match Fact record within your subscription.

GET https://api.sportmonks.com/v3/football/match-facts?api_token=YOUR_TOKEN

GET Match Facts by Fixture ID returns all Match Facts for a specific fixture. This is the most common entry point when building match preview or live match features.

GET https://api.sportmonks.com/v3/football/match-facts/{fixture_id}?api_token=YOUR_TOKEN

GET Match Facts by Date Range returns Match Facts for all fixtures within a given date range. Useful for pre-fetching facts across a full matchday.

GET https://api.sportmonks.com/v3/football/match-facts/between/{start_date}/{end_date}?api_token=YOUR_TOKEN

GET Match Facts by League ID returns Match Facts scoped to a specific league.

GET https://api.sportmonks.com/v3/football/match-facts/leagues/{league_id}?api_token=YOUR_TOKEN

Includes and filters

Each Match Facts endpoint supports the type, sport, and fixture includes, with up to three levels of nesting.

To filter down to specific fact types, use the facts filter with a comma-separated list of type IDs:

GET https://api.sportmonks.com/v3/football/match-facts/{fixture_id}?api_token=YOUR_TOKEN&include=type&filters=facts:1601,1602

You can also access Match Facts directly from a fixture by using the matchFacts include on any fixtures endpoint request. When using this approach, the havingLiveMatchFacts filter is also available, restricting results to fixtures with live match facts active, such as outcomes triggered by a red card or a goal.

What you can build with Match Facts

– Match preview modules covering head-to-head records, scoring trends, and first-to-score patterns for upcoming fixtures across the Premier League, Champions League, La Liga, Bundesliga, Serie A, and beyond
– Live match insight feeds that surface contextual facts as in-match events occur, such as updated outcome probabilities after a red card.
– Fantasy game integrations using scoring trend and situational data to inform pick recommendations and captain choices.
– Betting context features that display relevant historical patterns alongside pre-match markets.
– Automated match summaries using the natural_language field to render display-ready insight text without additional processing

Availability

Match Facts is a premium beta feature included in all Starter, Growth, Pro, and Enterprise plans. League coverage during the beta period is available in the Match Facts coverage sheet linked in the Football API v3 documentation. Coverage may expand as the feature moves towards a full release.

You can explore and test the Match Facts endpoints using the Sportmonks Postman collection or the API tester in MySportmonks.

Try it free. All paid plans include a 14-day free trial, and the forever-free plan gives you immediate access to the Danish Superliga and Scottish Premiership with no credit card required.

What are Match Facts?

Match Facts are pre-built contextual insights compiled from historical and live data for each fixture. They cover head-to-head records, scoring trends, first-to-score patterns, live match context, and situational data, delivered as structured records with a ready-to-display natural language field.

How do I retrieve Match Facts for a specific fixture?

Use GET Match Facts by Fixture ID with the fixture's ID, or add the matchFacts include to any fixtures endpoint request to retrieve them alongside the fixture record in a single call.

Can I filter Match Facts to specific insight types?

Yes. Use the facts filter with a comma-separated list of type IDs on any Match Facts request to return only the categories you need.

What is the havingLiveMatchFacts filter?

When using the matchFacts include on a fixtures endpoint request, the havingLiveMatchFacts filter restricts results to only fixtures that currently have live match facts available, such as real-time outcome probabilities triggered by goals or red cards.

Which leagues are covered by Match Facts?

Coverage during the beta period is listed in the Match Facts coverage sheet linked in the Football API v3 documentation. This is expected to expand as the feature develops.

Written by David Jaja

David Jaja is a technical content manager at Sportmonks, where he makes complex football data easier to understand for developers and businesses. With a background in frontend development and technical writing, he helps bridge the gap between technology and sports data. Through clear, insightful content, he ensures Sportmonks' APIs are accessible and easy to use, empowering developers to build standout football applications