Trends

Trends

Trends are time-based data points that describe how certain metrics evolve over the course of a match. Instead of giving you a single aggregated value (for example, total shots or total pressure), trends let you follow minute-by-minute (or period-by-period) developments for each team.

This makes trends ideal for:

• Visual timelines and graphs (momentum, pressure, xG over time, etc.)

• In-depth match analysis and storytelling

• Advanced models that care about when something happened, not just how much

A key example of a trend-based feature in the Football API is the Pressure Index, which exposes pressure values as a series of time-stamped data points.

Think of trends as time-series data for a single match: each record ties a value (like pressure) to a specific participant (team) and moment in the game.

---

How trends are structured

Trend data is exposed as lists of records attached to a fixture, usually via a feature-specific include (for example, pressure). Each record typically contains:

• A reference to the fixture

• A reference to the participant (team)

• The time within the match (minute, and in API 3 also the period)

• The value of the trend at that moment (for example, a pressure score)

Conceptually, a single trend record answers the question:

“At this point in the match, for this team, what was the value of this metric?”

Period and minute separation (API 3)

In API 3, trends are explicitly identifiable using:

• Period – which part of the match the value belongs to (for example, 1st half, 2nd half, extra time, etc.)

• Minute – the minute within that period

• Participant (team) – which team the record belongs to

This prevents ambiguity between, for example:

• A data point at 45+2 in the first half

• A data point at 47:00 in the second half

In addition, when a value is recorded during injury time, minute and extra minute are added together, so you can still plot or process it on a continuous time axis if needed.

Example: Pressure Index as a trend

For the Pressure Index, trends are returned as an array under the pressure key on a fixture. A simplified example looks like this:

"pressure": [
  {
    "id": 941884259,
    "fixture_id": 18804442,
    "participant_id": 2930,
    "minute": 6,
    "pressure": 0
  },
  {
    "id": 941884266,
    "fixture_id": 18804442,
    "participant_id": 9,
    "minute": 6,
    "pressure": 10.92
  }
]

Each record is a single point you can plot on a chart or use in your own models.

---

Requesting trends

Trends are not retrieved via a generic /trends endpoint. Instead, they are exposed through feature-specific includes on fixtures.

For example, to retrieve Pressure Index trends for a fixture, you add the pressure include to a GET Fixture by ID request:

https://api.sportmonks.com/v3/football/fixtures/18804442
  ?api_token=YOUR_TOKEN
  &include=pressure

The response will contain all standard fixture fields, plus a pressure array with the trend points, as shown above.

Always check the documentation of a specific feature (such as Pressure Index) to see which include name exposes its trends and how the payload is structured.

---

Working with trends in your application

1. Building graphs and timelines

Trends are perfect for visualising how a match develops. Common use cases:

• Pressure graphs – plot the Pressure Index per team over time

• Momentum charts – show when one team took control of the match

• Storytelling widgets – highlight key swings in dominance

A typical workflow:

1. Request the fixture with the relevant trend include (for example, pressure).

2. Group records by participant_id (home vs. away team).

3. Sort each group by time (minute / period).

4. Plot the values on a line chart.

2. Handling injury time and extra periods

Because API 3 clearly separates periods and minutes and correctly handles injury time, you can:

• Avoid overlapping values between halves

• Correctly mark data points that occur in added time

• Build accurate visual timelines that match the actual match flow

If you want a single continuous timeline (0–90+ minutes), you can:

• Use the minute plus added time as your x-axis value

• Combine this with the period information to distinguish first half, second half, and extra time where needed

3. Combining trends with other data

Trends become even more powerful when combined with:

• Events (goals, cards, substitutions)

• Statistics (shots, possession, xG)

• Odds or predictions

For example, you can annotate a pressure graph with goal events, or compare pressure swings to your pre-match probabilities.

---

API 2 vs API 3: what changed for trends?

The "Trends" behaviour was refined in API 3 to make it easier and safer to use in applications.

In API 2:

• Trend values for each team were identifiable only by minute.

• There was no clear separation between periods, so:

  • Values in injury time of the first half could overlap with values at the start of the second half.

  • This could result in abnormal or misleading lines if you plotted trends directly.

In API 3:

• All trend entities for a fixture are listed in a single list.

• Each trend record is identifiable using period, minute and participant (team).

• When a value is recorded during injury time, minute and extra minute are added together.

This leads to:

• Clearer, more consistent data

• No overlapping trend points across periods

• Smoother, more accurate graphs and analyses

For a high-level summary of this change, see the Trends section on the API Changes page.

---

When should I use trends?

Use trends whenever you need to answer questions like:

• “When did Team A start dominating the match?”

• “How did the pressure build up before the goal?”

• “Was this match a constant one-way attack or a game of swings?”

If you only need final totals (for example, total shots or average possession), regular statistics may be enough. But if you care about how things changed over time, trends are the right tool.

For a concrete, end-to-end example of a trend-based feature, check out the Pressure Index documentation.