Includes

On this page you will learn about includes and how they will enrich your response, so you will get exactly the API response you need/expect.

Enriching your data with 'Includes'

When you call one of our API addresses (endpoints), you usually get a basic response: just the essential details, like ID numbers and core information. However, you often need more, maybe the full team profiles, the match events, or related tracking data, all in one go, without making multiple calls.

That is exactly what the include= parameter is for.

With include=, you can enrich your response by bringing in related pieces of information (resources) in a single request.

• For example: Instead of just getting a match ID and team IDs, you can ask for the full team objects, the starting player line-ups, and the event timeline, all at once.

This process saves multiple trips back and forth to the server, simplifies your code, and gives you much richer data, much faster.

How includes work

When you call one of our API endpoints, by default, you receive a basic response, typically IDs and core fields. Using includes allows you to enrich that response by adding related resources in one request.

Simple include example

Suppose you want fixture data for a given date, and you want to know full team details alongside the fixture.

The date is in YYYY-MM-DD format.

GET https://api.sportmonks.com/v3/football/fixtures/date/2022-09-03
?api_token=YOUR_TOKEN

This returns the basic fixture information.

Response

{
  "data": [
    {
      "id": 18537988,
      "sport_id": 1,
      "league_id": 501,
      "season_id": 19735,
      "stage_id": 77457866,
      "group_id": null,
      "aggregate_id": null,
      "round_id": 275093,
      "state_id": 1,
      "venue_id": 336296,
      "name": "Hearts vs St. Johnstone",
      "starting_at": "2023-03-04 15:00:00",
      "result_info": null,
      "leg": "1/1",
      "details": null,
      "length": 90,
      "placeholder": false,
      "last_processed_at": "2023-03-02 00:15:27",
      "has_odds": true,
      "starting_at_timestamp": 1677942000
    },
    {
      "id": 18537977,
      "sport_id": 1,
      "league_id": 501,
      "season_id": 19735,
      "stage_id": 77457866,
      "group_id": null,
      "aggregate_id": null,
      "round_id": 275091,
      "state_id": 5,
      "venue_id": 8946,
      "name": "Hibernian vs Kilmarnock",
      "starting_at": "2023-02-18 15:00:00",
      "result_info": "Hibernian won after full-time.",
      "leg": "1/1",
      "details": null,
      "length": 90,
      "placeholder": false,
      "last_processed_at": "2023-02-25 14:55:39",
      "has_odds": true,
      "starting_at_timestamp": 1676732400
    },
    {
      "id": 18537990,
      "sport_id": 1,
      "league_id": 501,
      "season_id": 19735,
      "stage_id": 77457866,
      "group_id": null,
      "aggregate_id": null,
      "round_id": 275093,
      "state_id": 1,
      "venue_id": 8914,
      "name": "Rangers vs Kilmarnock",
      "starting_at": "2023-03-04 15:00:00",
      "result_info": null,
      "leg": "1/1",
      "details": null,
      "length": 90,
      "placeholder": false,
      "last_processed_at": "2023-03-02 00:15:27",
      "has_odds": true,
      "starting_at_timestamp": 1677942000
    }
    // And more...
  ]
}

By adding an include:

&include=participants

Your request becomes:

GET https://api.sportmonks.com/v3/football/fixtures/date/2022-09-03
?api_token=YOUR_TOKEN&include=participants

Now the response includes full team details (names, logos, venue info) rather than just team IDs.

Response

{
  "data": {
    "id": 18535605,
    "sport_id": 1,
    "league_id": 501,
    "season_id": 19735,
    "stage_id": 77457866,
    "group_id": null,
    "aggregate_id": null,
    "round_id": 274733,
    "state_id": 5,
    "venue_id": 8914,
    "name": "Rangers vs Celtic",
    "starting_at": "2023-01-02 12:30:00",
    "result_info": "Game ended in draw.",
    "leg": "1/1",
    "details": null,
    "length": 90,
    "placeholder": false,
    "last_processed_at": "2023-02-17 10:19:54",
    "has_odds": true,
    "starting_at_timestamp": 1672662600,
    "participants": [
      {
        "id": 53,
        "sport_id": 1,
        "country_id": 1161,
        "venue_id": 8909,
        "gender": "male",
        "name": "Celtic",
        "short_code": "CEL",
        "image_path": "https://cdn.sportmonks.com/images/soccer/teams/21/53.png",
        "founded": 1888,
        "type": "domestic",
        "placeholder": false,
        "last_played_at": "2023-02-26 15:00:00",
        "meta": {
          "location": "away",
          "winner": false,
          "position": 1
        }
      },
      {
        "id": 62,
        "sport_id": 1,
        "country_id": 1161,
        "venue_id": 8914,
        "gender": "male",
        "name": "Rangers",
        "short_code": "RAN",
        "image_path": "https://cdn.sportmonks.com/images/soccer/teams/30/62.png",
        "founded": 1873,
        "type": "domestic",
        "placeholder": false,
        "last_played_at": "2023-02-26 15:00:00",
        "meta": {
          "location": "home",
          "winner": false,
          "position": 2
        }
      }
    ]
  },

Multiple includes in one request

You can include several related resources in a single call. For instance:

&include=participants;events

would bring both full team data and all match events (goals, cards, substitutions) into the same response.

Nested includes

Some includes have further relationships. For example, you might ask for lineups.player if you want player details within the lineups object. The dot-notation lets you go deeper into related data.

When using includes, two key things to remember:

• Each endpoint supports a specific set of include options (so check what’s available for that endpoint)

• Adds extra data to the response, which may affect performance or query complexity, so use only the includes you actually need.

Best practices & performance for using 'includes'

The include= parameter is powerful, but to get the most value and avoid slowing down your application, you need to use it smartly.

When to use 'Includes'

You should use 'includes' when:

• You need the related data immediately. If you know you'll use the team's profile information as soon as you fetch the match fixture, include it.

• You want to reduce latency. By making one large request instead of many small ones, you save multiple trips to the server, which speeds up your integration significantly.

• You want to simplify your code. Using one clean request is always easier to manage and maintain than writing code to handle many separate API calls.

You should skip 'includes' when:

• You only need the core ID fields.

• The related data is optional or rarely used by your application. Keeping the response light makes it faster.

⚠️ What to watch out for

• Response size: Adding many includes, especially nested ones (like lineups.player), increases the data size significantly. This uses more bandwidth and slows down the response time for both your server and your users.

• Varying support: Not every extra piece of data is available for every API address. You must check the documentation to verify that the 'include' you want is supported by that specific endpoint.

• Complexity: Nested 'includes' requires more processing work from both the server and your application's code, which can add complexity to maintenance.

Tips for efficient use

1. Be strict: Only include the extras you genuinely need right now; avoid "just in case" includes.

2. Monitor performance: Regularly check your response times and the size of the data you receive. Test your feature with and without includes to understand the exact impact on speed.

3. Prioritise caching: Save the results of heavy requests (those with many includes) to your own cache. This means you only have to fetch that large payload once.

4. Filter aggressively: Use filtering and pagination alongside your 'includes' to ensure you don’t overload your system with data you don't need.

5. Plan for fallback: Provide fallback logic in your code in case some included data is temporarily missing (e.g., if a field is only available during live matches).

Includes-reference (endpoint-by-endpoint)

Below you’ll find each major endpoint grouped by category. For each endpoint, we show the available include= options, what they mean, and any special notes. Use this as your go-to reference when deciding what to include in a request.

Fixtures & Livescores

Endpoint: /v3/football/fixtures/{id} (and similar fixtures/livescores endpoints)

Include	Description	Notes
participants	Full team objects for the fixture (team name, logo, venue, etc)	Works for fixture endpoints; check nested includes like participants.coaches
events	Full list of match events (goals, cards, substitutions, etc)	Includes nested sub-objects (player, team)
lineups	Full lineup data for both teams (players, positions, numbers)	Might only be available once lineup is confirmed
ballCoordinates	Tracking data of the ball in the fixture (x/y coordinates)	Real-time / live tracking; may be premium or delayed
state	Current match state (scheduled, inplay, finished, postponed)	Useful for live updates
scores	Detailed scoring breakdown by period (HT, FT, ET)	Check endpoint version for availability
metadata	Additional fixture metadata (pitch type, weather, etc)	Some fields may be empty for older matches

Teams / Players

Endpoint: /v3/football/teams/{id} & /v3/football/players/{id}

Include	Description	Notes
metadata	Detailed team or player metadata (preferred foot, height/weight, etc)	Check plan tier for full coverage
position	General position info (for players)	May overlap with default fields
statistics	Historical or current season statistics for the entity	Requires correct filters (e.g., season)
transfers	Transfer history/quota for players or teams	Only visible where supported

Standings, Seasons & Statistics

Endpoint: /v3/football/standings/seasons/{id} & similar.

Include	Description	Notes
details.type	Includes special types (e.g., expected points table, xPTS)	Use correct type ID (e.g., 7393 for xPTS).
topscorers.topscorer	Full data for top scorers rather than just IDs	Only works for seasons/stages with this data
statistics.details.type	Detailed statistic types across entity (team/player)	May need filter teamStatisticSeasons or playerStatisticSeasons

Advanced & specialised endpoints

Endpoint: e.g., /v3/football/fixtures/date/{date} / /v3/football/predictions etc.

Include	Description	Notes
statistics.type	Retrieves match statistics of a specific type (e.g., shots, passes) using the “type” filter.	Must specify the correct type_id for the statistic.
lineups.details.type	Returns lineup details for each player, filtered by statistic type (e.g., minutes played, fouls) for a match.	Available on fixtures endpoints; large payloads.
events.type	Returns events of a specific type in a match (goals, cards, offsides) using the “type” filter.	Use when you want only a subset of events rather than all.

Summary & next steps

You now know what includes are, how to use them, and how to see which includes are available per endpoint. With this tool, you can enrich your API responses, reduce the number of separate requests, and get a more complete data set in one go.

Here’s what to do next:

• Review your integration and decide which includes you actually need.

• Use the reference tables above to pick the correct include names for your endpoints.

• Test your requests, monitor response size and performance, and adjust your includes accordingly.

• If you require deeper data (nested includes), use nested includes, but always check whether they are supported and efficient.

Not seeing all the data you expected to see? Check out our tutorial about pagination.