# Includes ### 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](https://docs.sportmonks.com/football/api/request-options/includes), 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. {% hint style="info" %} The date is in YYYY-MM-DD format. {% endhint %} ```http GET https://api.sportmonks.com/v3/football/fixtures/date/2022-09-03 ?api_token=YOUR_TOKEN ``` This returns the basic fixture information.
Response ```json5 { "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: ```http &include=participants ``` Your request becomes: ```http 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 ```json5 { "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: ```http &include=participants;events ``` would bring both full team data *and* all match events (goals, cards, substitutions) into the same response. **Time-series includes (Trends)** Some includes return **time-series data** rather than single values or static objects. These are called **trends** and show how metrics evolve minute-by-minute throughout a match. For example: * `include=pressure` returns the Pressure Index as an array of time-stamped values * Other trend-based includes show possession, passing accuracy, attacks, etc. over time **Trends require special handling** because you're working with arrays of time-based data points rather than simple objects. If you plan to build graphs, timelines, or analyse momentum shifts, see our full Trends tutorial to learn: * How trend data is structured (periods, minutes, participants) * How to build graphs and visualizations * When to use trends vs regular statistics * How to handle injury time and extra periods 💡 **Quick example:** Instead of getting "Team A had 55% possession," trends give you an array showing possession percentage at minute 5, minute 10, minute 15, etc., allowing you to visualise momentum changes. #### 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. * **Trend data complexity**: Some includes (like `pressure` or trend-based statistics) return arrays of time-stamped values rather than single objects. These require different processing logic. See [the Trends tutorial](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/trends) for guidance on handling time-series data. #### 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 | | `pressure` | Pressure Index trend data (time-series) | Returns array of time-stamped pressure values. See [Trends](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/trends) for working with time-series data | | `trends` | Various match trends (possession, passing, attacks) | Time-series data; requires special handling. See Trends tutorial | #### **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](https://docs.sportmonks.com/football/tutorials-and-guides/tutorials/enrich-your-response/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](https://docs.sportmonks.com/football/tutorials-and-guides/tutorials/introduction/pagination). ### See also #### Prerequisites * [API Structure & Navigation](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/api-structure-and-navigation) - Understand endpoint organization * [Quick Start Guide](https://docs.sportmonks.com/v3/welcome/quick-start-guide) - Make your first request #### Common include use cases * [Fixtures Tutorial](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/livescores-and-fixtures/fixtures) - Most common use case for includes * [Statistics](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/statistics) - Include statistics.type for match data * [Livescores](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/livescores-and-fixtures/livescores) - Enrich live data with includes * [Lineups](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/lineups-and-formations) - Include detailed lineup data * [Trends](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/trends) - Include form analysis * [Expected Goals](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/expected) - Include xGFixture and lineups.xGLineup #### Advanced topics * [Nested Includes Guide](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes/tips-and-tricks) - Chain multiple levels of data * [States](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes/states) - Include fixture states * [Events](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes/events) - Include match events * [Scores](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes/scores) - Include score data #### Optimisation * [Rate Limiting](https://docs.sportmonks.com/v3/api/rate-limit) - Optimize include usage to stay within limits * [Performance Best Practices](https://docs.sportmonks.com/v3/welcome/best-practices) - Efficient data retrieval * [Pagination](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/introduction/pagination) - Understand includes don't paginate #### Reference * [Entity Pages](https://docs.sportmonks.com/v3/endpoints-and-entities/entities) - See all available includes per entity * [Types Reference](https://docs.sportmonks.com/v3/definitions/types) - Decode type IDs in included data