# Welcome Welcome to Sportmonks! We're thrilled to have you here. Explore our football documentation to access comprehensive information about Sportmonks’ Football API.


Getting started	Watch a detailed tutorial video of how you can get started using our API.	/pages/VTkYXtB3Q0qT6q2dME5c	/files/wc6gEOP0SdFnbfzlXy2l
Request options	Learn how to optimise your API requests with filters, includes, and field selection	/pages/sZ3V16yVx1JMhvJs7elP	/files/6EdL6iNVcYIkcNLqd3eg
Endpoints	View all the Endpoints we have available in our API.	/pages/T7U6viFDeRG8KXtQ33k7	/files/jkV6uyZflAqRaaP1298r
Best Practices	Learn how to use our API in the best way possible.	/pages/hji2FKO8bCwcfoVuKG1U	/files/6KXOkeOvki5ucpWP8UHW
Odds documentation	Take a look at our documentation dedicated to our odds features.	/spaces/d833Stdf2lpP4dN5FgEm	/files/P11UTtXeD0K1ru49vzcg
Core documentation	Dive into our core documentation.	/spaces/z0kWjB5EvZvqGsozw8vP	/files/Rml5Jt8BLaiBrpaLtwgm
Tutorials	Learn more about specific features of our API by reading out tutorials.	/pages/T9a1iOOSCP55nE9cWRJR	/files/p0wDOrCcjW7BdpmqjB22
Guides	Read how to build the application of your dreams with our guides.	/pages/caSYgzbGlXVFObqF4fJ2	/files/YDKvfMyRZyQrJFjviSQq
Changelog	Keep in touch with the latest changes we have pushed in our API.	/pages/BdMgUT2IhZvPvFzNxW9z	/files/yoIprYBTJFXbvUkynHdt

{% hint style="success" %} If you need help locating specific topics, simply use the **search bar** at the top right corner of the page. The search bar, located at the top-right corner of the documentation, makes finding relevant content quick and intuitive. Type any keyword—whether it’s a complete word or a partial match—and you’ll see immediate, filtered results. You can refine your search by using more specific terms or phrases to narrow down the options. This is particularly useful if you’re unsure which category your topic might appear in. Give it a try and discover guides and other resources tailored to your interests. {% endhint %} We hope you find the information you need to build your dream football application! If you have any questions, feedback, or need assistance, don't hesitate to reach out to our dedicated support team at [support@sportmonks.com.](mailto:support@sportmonks.com) # Getting Started We'll briefly inform you about the features of our API, and then you can explore our documentation for yourself. You will also find out how to create **your** dream application. Sportmonks offers standard REST APIs. Requests are sent with URLs and responses will be returned in **JSON format**. Every authentication is spearheaded by an API token. We have assembled a library of all of our endpoints including example requests in **Postman**. {% embed url="" %} {% hint style="info" %} We also offer detailed postman documentation with examples and a complete up-to-date version of all our endpoints. Below is a button that lets your fork the collection or import it \ [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316?action=collection%2Ffork\&collection-url=entityId%3D11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316%26entityType%3Dcollection%26workspaceId%3D17c720d0-d97b-42a9-9ea7-23260ed53ddf) {% endhint %} Short introduction to Sportmonks: Now you know who we are, what we do, what we offer, and how we can help you: We suppose you want to get started right away. Head over to our [Getting Started section](/v3/welcome/making-your-first-request), where you'll create your own API token and create your first request What else do we cover in the documentation? * [Getting started ](/v3) * [API section](/v3/api/syntax) * [Endpoint overview](/v3/endpoints-and-entities/endpoints) * [Entities explained ](/v3/endpoints-and-entities/entities) * [Tutorials](/v3/tutorials-and-guides/tutorials) * [How-to guides](/v3/tutorials-and-guides/guides) * [Definitions](/v3/definitions/response-codes) **API structure**

### Persona-based getting started paths Different developers have different needs and experience levels. This document provides tailored getting started paths for each user persona, helping them find the most relevant documentation quickly and reducing time-to-first-success. #### Choose your path Select the path that best describes you to get started quickly with the right resources: #### New to APIs? **You're here to:** Learn what APIs are and how to use Sportmonks for the first time. #### Your learning path **Step 1: Understand the basics** * [What is an API?](https://www.sportmonks.com/glossary/application-programming-interface/) - Learn API fundamentals * [What can you do with Sportmonks?](https://docs.sportmonks.com/v3/welcome/what-can-you-do-with-sportmonks-data) - See what's possible **Step 2: Get set up** * [Authentication guide](https://docs.sportmonks.com/v3/welcome/authentication) - Get your API token * [Making your first request](https://docs.sportmonks.com/v3/welcome/making-your-first-request) - Send your first API call **Step 3: Learn core concepts (15 min)** * [API structure & navigation](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/api-structure-and-navigation) - How the API is organised * [Fixtures tutorial](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/livescores-and-fixtures/fixtures) - Working with match data * [Includes tutorial](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes) - Get more data in one request **Step 4: Build something simple (10-15 min)** * [Build a simple livescore app](https://www.sportmonks.com/blogs/building-a-real-time-livescore-app-with-a-football-api-best-practices/)- Step-by-step tutorial * [Understanding responses](https://www.sportmonks.com/glossary/json-response/) - Read API responses * [Common beginner mistakes](https://www.sportmonks.com/blogs/5-common-mistakes-developers-make-with-football-apis-and-how-to-avoid-them/) - Avoid pitfalls #### Experienced developer, new to Sportmonks? **You're here to:** Get productive quickly with Sportmonks' most powerful features. #### Your fast-track path **Step 1: Quick setup** * [Authentication](https://docs.sportmonks.com/v3/welcome/authentication) - Get your token * [Quick start guide](https://docs.sportmonks.com/v3/welcome/quick-start-guide) - Make your first request * [API structure](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/api-structure-and-navigation) - Understand organisation **Step 2: Power features** * [Advanced includes](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes) - Combine data efficiently * [Filter & select](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/filter-and-select-fields) - Optimise responses * [Rate limiting](https://docs.sportmonks.com/v3/api/rate-limit) - Understand limits **Step 3: Essential tutorials** * [Livescores & fixtures](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/livescores-and-fixtures) - Core match data * [Statistics](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/statistics) - Advanced stats * [States & types](https://docs.sportmonks.com/v3/definitions/states) - Reference data **Step 4: Optimise** * [Best practices](https://docs.sportmonks.com/v3/welcome/best-practices) - Production-ready code * [Error handling](https://docs.sportmonks.com/v3/api/error-codes) - Handle errors properly * [Performance tips](https://www.sportmonks.com/blogs/10-tips-for-maximising-sportmonks-football-api-usage-best-practices-for-developers/) - Scale efficiently **Pro tips:** * Use [ID finder](https://my.sportmonks.com/resources/id-finder) to discover entity IDs * Test with [Postman collection](https://postman.sportmonks.com/) * Cache reference data (types, states, leagues) #### Migrating from API v2? **You're here to:** Upgrade from API v2 to v3 smoothly and quickly. #### Your migration path **Step 1: Understand changes (10 min)** * [Key differences overview](https://docs.sportmonks.com/v3/welcome/differences-between-api-2-and-api-3) - What changed * [API changes](https://docs.sportmonks.com/v3/welcome/differences-between-api-2-and-api-3/api-changes) - Detailed breakdown * [Syntax changes](https://docs.sportmonks.com/v3/welcome/differences-between-api-2-and-api-3/syntax-and-filters) - New syntax **Step 2: Breaking changes checklist** * **Participants replace localTeam/visitorTeam** - Update team includes * **New include syntax** - Use semicolons (`;`) instead of commas * **New pagination** - No more `total_pages` in response * **Rate limits per entity** - Not per endpoint anymore * **Statistics only show recorded values** - No default zeros * **Trends structure changed** - New period-based format * **Bookmaker IDs changed** - Use `legacy_id` for mapping **Step 3: New features to explore** * [New endpoints](https://docs.sportmonks.com/v3/welcome/differences-between-api-2-and-api-3/new-endpoints-and-data-features) - What's new in v3 * [Expected goals (xG)](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/expected) - Advanced metrics * [Trends analysis](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/trends) - Form tracking * [Pressure index](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes/pressure-index) - Match momentum **Migration checklist:** ``` □ Update base URL to /v3/ □ Replace include commas with semicolons □ Change localTeam/visitorTeam to participants □ Update pagination logic (no total_pages) □ Handle null statistics (not zeros) □ Test all endpoints in your app □ Update error handling for new codes □ Review rate limits per entity ``` ### Building specific applications? Choose your application type for a focused guide: #### Livescore app **What you'll build:** Real-time match tracker with scores, events, and lineups. **Your path** 1. **Core features** * [Livescores tutorial](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/livescores-and-fixtures/livescores) - Real-time scores * [Events tutorial](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes/events) - Goals, cards, subs * [Lineups tutorial](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/lineups-and-formations) - Team lineups 2. **Enhancement features (15 min)** * [Scores by period](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes/scores) - Half-time scores * [States](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes/states) - Match status (NS, LIVE, FT) * [Fixtures tutorial](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/livescores-and-fixtures/fixtures) - Match details 3. **Optimisation** * [Polling strategy](https://docs.sportmonks.com/v3/welcome/best-practices) - How often to refresh * [Rate limiting](https://docs.sportmonks.com/v3/api/rate-limit) - Stay within limits * [Caching strategy](https://www.sportmonks.com/blogs/caching-and-optimisation-strategies-for-high-volume-football-api-usage/) - Improve performance 4. **Polish** * [Error Handling](https://docs.sportmonks.com/v3/api/error-codes) - Handle failures * [Filtering](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/filter-and-select-fields) - Show specific leagues **📱 Quick Implementation:** ```javascript // Fetch live matches with events and lineups const response = await fetch( 'https://api.sportmonks.com/v3/football/livescores/inplay?api_token=YOUR_TOKEN&include=scores;events;participants;lineups' ); const liveMatches = await response.json(); // Poll every 10 seconds for updates setInterval(async () => { const updates = await fetch( 'https://api.sportmonks.com/v3/football/livescores/latest?api_token=YOUR_TOKEN&include=scores;events' ); // Update your UI with changes }, 10000); ``` #### Betting platform **What you'll build:** Platform with odds, predictions, and statistics. **Your path:** 1. **Foundation** * [Fixtures tutorial](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/livescores-and-fixtures/fixtures) - Match data * [Statistics](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/statistics) - Performance data * [Head-to-head](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/livescores-and-fixtures/fixtures#get-fixture-by-head-to-head) - H2H records 2. **Odds & predictions** * [Pre-match odds](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/odds-and-predictions/pre-match-odds) - Bookmaker odds * [Live odds](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/odds-and-predictions/live-inplay-odds) - In-play odds * [Predictions](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/odds-and-predictions/predictions) - ML predictions * [Value bets](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/odds-and-predictions/predictions/value-bet) - Best value 3. **Advanced stats** * [Expected goals (xG)](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/expected) - Performance metrics * [Trends](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/trends) - Form analysis * [Team statistics](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/statistics/team-statistics) - Team performance 4. **Implementation** * [Markets & bookmakers](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/odds-and-predictions) - Understanding odds structure * Plan requirements - What you need * [Best practices](https://docs.sportmonks.com/v3/welcome/best-practices) - Production tips #### Fantasy football **What you'll build:** Fantasy league with player stats and scoring. **Your path** 1. **Player data** * [Players](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/teams-players-coaches-and-referees) - Player profiles * [Player statistics](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/statistics/players-statistics) - Performance metrics * [Lineups](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/lineups-and-formations) - Starting players 2. **Scoring system** * [Statistics types](https://docs.sportmonks.com/v3/definitions/types/statistics/player-statistics) - Available stats * [Fixture statistics](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/statistics/fixture-statistics) - Match stats * [Events](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes/events) - Goals, assists, cards 3. **League management** * [Fixtures by date](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/livescores-and-fixtures/fixtures#get-fixture-by-date) - Gameweek fixtures * [Season schedule](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/season-schedule) - Plan gameweeks * [Livescores](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/livescores-and-fixtures/livescores) - Live scoring 4. **Advanced features** * [Expected goals](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/expected) - xG for players * [Trends](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/trends) - Form indicators * [Transfers](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/transfers) - Transfer news **Sample fantasy points calculation:** ```javascript const calculatePoints = (playerStats) => { let points = 0; // Goals: 5 points each points += (playerStats.goals || 0) * 5; // Assists: 3 points each points += (playerStats.assists || 0) * 3; // Clean sheet (goalkeeper/defender): 4 points if (playerStats.cleansheet && ['GK', 'DEF'].includes(playerStats.position)) { points += 4; } // Yellow card: -1 point points += (playerStats.yellowcards || 0) * -1; // Red card: -3 points points += (playerStats.redcards || 0) * -3; return points; }; ``` #### Stats dashboard **What you'll build:** Analytics dashboard with trends, comparisons, and visualizations. **Your path** 1. **Statistics foundation** * [Statistics tutorial](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/statistics) - Overview * [Season statistics](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/statistics/season-statistics) - League stats * [Team statistics](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/statistics/team-statistics) - Team metrics * [Player statistics](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/statistics/players-statistics) - Player metrics 2. **Advanced metrics** * [Expected goals (xG)](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/expected) - Performance analysis * [Trends](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/trends) - Form tracking * [Pressure index](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes/pressure-index) - Match control 3. **Comparisons** * [Head-to-head](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/livescores-and-fixtures/fixtures#get-fixture-by-head-to-head) - Team comparisons * [Standings](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/standings) - League tables * [Filter & select](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/filter-and-select-fields) - Custom queries 4. **Visualisation tips** * [Statistics types reference](https://docs.sportmonks.com/v3/definitions/types/statistics) - Understand data * Data processing - Clean and format * [Best practices](https://docs.sportmonks.com/v3/welcome/best-practices) - Optimise **Dashboard components:** * Team form chart (last 10 matches) * xG vs actual goals scatter plot * Player comparison radar charts * League-wide statistics tables * Trend lines for key metrics ### Additional resources by persona #### For beginners **Helpful Guides:** * [API glossary](https://www.sportmonks.com/glossary/) - Common terms explained * [Understanding JSON](https://www.sportmonks.com/glossary/json-response/) - How to read responses * [Postman tutorial](https://www.postman.com/sportmonks-api) - Test without code * [Common errors](https://docs.sportmonks.com/v3/api/error-codes) - Fix issues #### For experienced developers **Advanced topics:** * [Nested includes](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes/tips-and-tricks) - Complex queries * [Bulk operations](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/introduction/pagination) - Process multiple entities **Performance:** * [Caching strategies](https://docs.sportmonks.com/v3/welcome/best-practices#caching) - Speed up apps * Database Design - Store efficiently * Monitoring - Track usage #### For migrators **Migration tools:** * [API v2 to v3 Mapping](https://docs.sportmonks.com/v3/welcome/differences-between-api-2-and-api-3) - Endpoint changes ### Need help? Can't find what you're looking for? We're here to help: #### Quick help * **Search documentation** - Use search bar above * **Browse tutorials** - [All Tutorials](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials) #### Direct Support * **Email:** * **Sales:** For plan questions #### Report Issues * **Bug report:** [Submit Issue](maito:support@sportmonks.com) * **Documentation feedback:** Use smile /frown emojis * **Feature request:** [Submit Request](https://maito:support@sportmonks.com/) ### See also * [Full tutorial index](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials) * [API reference](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints) * [Best practices](https://docs.sportmonks.com/v3/welcome/best-practices) * [Error codes](https://docs.sportmonks.com/v3/api/error-codes) # Quick Start Guide Setting up your first API request doesn’t have to be difficult. Whether you’re a developer, analyst, or product owner, this **Quick Start Guide** will walk you through the entire process: from account setup to your first successful call. #### 📄 What’s Inside the Guide? * ✅ How to create and verify your MySportmonks account * 🔐 How to generate and secure your API token * 🔧 How to structure your first API request * 📚 How to explore the documentation effectively * 💡 Tips for choosing the right subscription plan {% file src="/files/Z6btsBs8Q7ngZQ3tBMGC" %} The PDF is a short, visual, step-by-step guide designed to get you up and running in under **6 minutes**. # Most important docs pages Whether you're just getting started or refining your integration, these are the pages you’ll use most. Bookmark them, explore them, and make the most of your Sportmonks journey. #### 🧭 Introduction tutorial **Kickstart your Sportmonks experience.**\ New to our API? Start here. Learn how authentication works, how endpoints are structured, and how to make your first successful request. Step-by-step guidance helps you move from your first call to confident querying. > 🎯 *Perfect for developers integrating Sportmonks for the first time.* [Go to Introduction Tutorial →](https://docs.sportmonks.com/football/tutorials-and-guides/tutorials/introduction) #### 🔧 Request Options **Shape your data, your way.**\ Master the art of efficient requests. Learn how to filter, sort, paginate, and include related data without unnecessary overhead. Build smaller, faster, and more precise responses. > ⚙️ *Essential for performance-focused applications.* [Explore Request Options →](https://docs.sportmonks.com/football/api/request-options) #### 📁 Demo Response Files **See it before you build it.**\ Preview actual JSON responses for fixtures, teams, players, and standings. These files are ideal for planning data models, front-end components, or testing integrations before going live. > 🧩 *Useful for developers designing data structures and prototypes.* [View Demo Files →](mailto:undefined) #### ✅ Best Practices **Build smarter and scale confidently.**\ Avoid common pitfalls with expert guidance on topics like caching, rate-limiting, timezone handling, and database synchronisation. These principles ensure your integration remains stable and efficient as you grow. > 🛠 *Highly recommended for production setups.* [Read Best Practices →](https://docs.sportmonks.com/football/welcome/best-practices) #### 📚 Guides Collection (incl. Components Guide) **Go beyond the basics.**\ Explore structured tutorials packed with real examples. Learn how to build modular and reusable data structures with the Components system, and how to combine endpoints effectively. > 📘 *For developers expanding from simple requests to advanced builds.* [Browse Guides →](https://docs.sportmonks.com/football/tutorials-and-guides/guides/how-to-use-components) #### 🔄 States **Track every match’s lifecycle.**\ Understand how fixture states define the timeline of a match — scheduled, live, halftime, finished, or cancelled. Use them to power live dashboards and notifications with real-time accuracy. > ⏱ *Key for live-score and timeline applications.* [Learn about States →](https://docs.sportmonks.com/football/definitions/states) #### ⚡ Events **Follow every key moment.**\ Events capture the action: goals, cards, substitutions, and more. Learn how to include and interpret them to build detailed match feeds, commentary systems, and visual timelines. > 🎯 *Ideal for match trackers and live commentary widgets.* [Read Events Docs →](mailto:undefined) #### 📊 Statistics **Turn data into insight.**\ Dive deep into performance metrics like shots, passes, possession, and expected goals. Use this data to fuel analytics dashboards, fantasy scoring, and predictive models. > 📈 *Perfect for analytics, scouting, and performance tools.* [Explore Statistics →](https://docs.sportmonks.com/football/definitions/types/statistics) # What can you do with Sportmonks' data? Sportmonks provides a rich and diverse array of sports data, offering you the ability to build, enhance, and optimise sports-related experiences. Whether you're creating live apps, analytics tools, or enriched websites, our data gives you the fuel to power those ideas. Below are example use cases and guiding patterns, along with pointers to the relevant endpoints you can start with. ### **1. Create live football applications** Use our real-time endpoints to keep your users in sync with live matches and changes. **Possible applications** * **Livescore apps**: Show ongoing match scores, minute-by-minute events, substitutions, cards, lineups. * **Fantasy sports platforms**: Update player statistics in real time so fantasy leagues reflect current performance. * **Betting / in-play portals**: Deliver live odds, in-match statistics, and instant match outcomes.

**Endpoint starting points** * [`/livescores/inplay`](https://docs.sportmonks.com/football/tutorials-and-guides/tutorials/livescores-and-fixtures/livescores?u) – returns matches currently in play. * [`/livescores/latest`](https://docs.sportmonks.com/football/tutorials-and-guides/tutorials/livescores-and-fixtures/livescores) – returns fixtures that had updates within the last 10 seconds (useful as your change trigger). * Use includes (e.g. `include=events,lineups,statistics`) to enrich your live match data. * Use [`standings/live/leagues/{league_id}`](mailto:undefined) for live standings within a league. ### **2. Enrich football websites with data** Integrate our data into blogs, news portals, fan sites, or club pages to provide richer context and content. **Use cases** * **Pre-match & post-match articles**: Include past match stats, head-to-head history, recent form. * **Team & player profiles**: Show full career stats, performance trends, transfers. * **League pages**: List active & historical seasons, current standings, upcoming fixtures. * **“On this day” features**: Historical matches on the same date.

**Key endpoints to use** * `GET /leagues` + includes for `currentSeason` and `seasons.` * `GET /fixtures/date/{date}` for matches on a specific date. * `GET /statistics/season/{season_id}` to fetch season-wide performance stats. * `GET /stages` to retrieve structure (e.g. which stages a season contains). **Examples** ```bash GET /v3/football/leagues?api_token=…&include=currentSeason,seasons GET /v3/football/fixtures/date/2025-10-01?api_token=…&include=participants,venue ``` Use caching, selective includes, and filtering to keep payloads efficient. ### **3. Power analytics & insights** With deep statistics, you can build analytical tools, dashboards, or prediction engines. **Possible products** * **Predictive models**: estimate match outcomes, over/under probabilities, player performance. * **Performance dashboards**: track team or player trends, strengths/weaknesses over time. * **Trend discovery**: identify up-and-coming players, momentum shifts, league-wide shifts.

**Helpful endpoints** * `/statistics/season/{season_id}` : Full-statistics for a season. * `/statistics/fixture/{fixture_id}` : Detailed match-level statistics. * Aggregation endpoints or filtered stats (e.g. per team or per player over time). **Advice** * Normalise data across seasons (in case rules or formats change). * Use time-based windows (last 5 matches, rolling averages). * Combine with external data (injuries, weather) for richer insights. ### **4. Enhancing betting platforms** Data accuracy and speed are crucial in betting or odds-driven contexts. **Use cases** * **Odds display**: Show up-to-date betting odds (pre-match & in-play). * **Prop bets & special markets**: Use player stats or match dynamics (cards, corners, goal timing). * **Insight-driven recommendations**: Historical head-to-head data, form, and trends to guide users.

**Endpoints to leverage** * Odds endpoints (`/odds`, `/inplayOdds`) to fetch bookmaker markets and live odds. * Prediction / probability endpoints (if available). * Combine with live match data (`livescores`) and stats to enrich betting features. **Caveats** * Respect rate limits and latency (speed matters). * Be precise with includes and filters to minimise data overhead. ### 5. Real-time and event-driven apps Build apps that respond instantly to events or changes in matches. **Use cases** * **Match alerts & notifications**: Notify users instantly when a goal is scored, a red card occurs, or a match starts/ends. * **Live commentary widgets**: Provide minute-by-minute descriptions, event triggers (goals, substitutions, penalties). * **Head-to-head live comparison**: As a match progresses, continuously compare team statistics (shots, possession, passes) side by side. **Endpoint starting points** * `/livescores/inplay` : Gets currently live matches. * `/fixtures/{fixture_id}` + `include=events,statistics,participants` : Get detailed event and stat data for the match. * `/livescores/latest` : Get matches updated in the last few seconds (good for polling). ### 6. Hybrid content + interactive experiences Merge static content with interactive, data-powered features to delight users. **Use cases** * **“On this day in Football”**: Show historical matches on the same date, with links between past and present. * **Interactive timeline of a match**: Display a scrollable timeline (first half / second half) with events (goals, substitutions, cards). * **Fan polls & predictions**: Let users pick match outcomes or “Man of the Match” and later compare against model predictions. **Endpoint starting points** * `/fixtures/date/{date}` : Get matches on a particular date (useful for “On This Day”). * `/fixtures` with filters / includes for events, statistics, participants. * `/predictions` / `/probabilities` endpoints to fetch model or probabilistic insights (for poll comparison). ### 7. Scouting, club & transfer intelligence Support professional workflows around recruitment, strategy, and transfer decisions. **Use cases** * **Transfer market tracker**: Monitor transfer rumors, completed deals, and assess performance post-transfer. * **Player recruitment tools**: Rank potential signings by metrics, compare to existing squad members. * **Tactical analytics platform**: Assess how players perform under different tactics (passing networks, heatmaps). **Endpoint starting points** * `/transfers` : List transfer events, filter by team / player / date. * `/players` + includes (statistics, team, performance) for detailed profiles. * `/fixtures` + includes and filters to analyze match specifics and map performance in context. ### Customer stories & inspiration | Customer | What they built / benefit | Link | | ---------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | SoFIFA | Integrated real match data into a football game mode | | | Scoreplay | Automated media workflows, image → game matching, schedules | | | ShiftOneZero / Dinamo Zagreb | Fan app with real-time stats, fixtures, fan features | | | Botbrains.io / Liveticker.AI | AI-driven live match commentary across 12+ languages | | | Footi | Lightweight football news + live platform | | > 📌 Tip: Use these stories to spark ideas as you’re not limited to one domain. Many customers combine multiple use cases (e.g. analytics + content + live). ### Still not sure? The possibilities with sports data are vast and not limited to what’s listed here. With over 20,000 customers (each pursuing unique ideas), many use cases may already have been explored. If your idea isn’t listed above, it doesn’t mean it’s not possible, reach out to us, check our [**case studies**](https://www.sportmonks.com/football-api/case-studies/), or explore other endpoints (e.g. transfers, news, predictions) and see how they might fit into your concept. **Need more inspiration or guidance?** Browse through our documentation for more examples, or reach out to us directly. We’re here to help you explore the possibilities. Contact us through our [contact form](https://www.sportmonks.com/contact-support/) or send an email to . # Differences between API 2 and API 3 ## Introduction We've made various changes to our new API. These changes result in some groundbreaking differences between API 2 and API 3. This section of the documentation is here to help you understand how to adopt all the latest changes, improve the quality of your applications and streamline your development experience. Here's a quick overview of some differences between API 2 and API 3.0: * API changes * States and types * Strict typing * Include changes * Rate limit per entity * Syntax, extensive filtering and select options * New data features and endpoints {% hint style="info" %} Checking the differences between two API versions can help you identify changes that may affect your code and make any necessary adjustments. Please don't hesitate to contact us with any questions or concerns. {% endhint %} {% embed url="" %} To better serve our growing customer base and meet the demand for more sports-related services, we have introduced a new API: Sportmonks V3. This updated configuration is designed to deliver improved reliability, broader coverage, and a variety of new data features and endpoints that were simply not possible with API V2. You can find these enhancements [here](/v3/welcome/differences-between-api-2-and-api-3/new-endpoints-and-data-features). To maintain the highest possible data quality, the validation for V3 is stricter. Additionally, the entire structure of V3 is different compared to V2. As a result, data discrepancies may arise between V2 and V3. We strongly recommend using the newest version of our Football API (V3) to benefit from improved data quality. The data quality of V3 is way more reliable and accurate due to its new structure and the validation methods we use. Furthermore, future innovations will only be available on API 3.0, so we recommend switching as soon as possible. # API Changes ## States and Types We introduced states and types to ensure data quality and consistency for specific fields. ### States A fixture moves between several statuses. It has an initial status (NS), can be delayed (DELA), has been finished (FT) or any of the statuses described on the [states page](/v3/definitions/states). You could also use the [states endpoint](/v3/endpoints-and-entities/endpoints/states) to retrieve all possible states. ### Types Something has a type, when there are multiple variants of a certain variant. For example, types for referees. Referees can be the head referee, the assistant referee or the fourth official. Due to types we qualify which variant of the belonging entity the specific referee is. This was introduced to ensure all sports will follow the exact same structure in API 3.0. **New types:** Position ID and detailed position ID are new types. Also, periods, sidelined, referees, events, standings, metadata, formations, colors, injuries, suspensions, predictions, and stats contain fields that belong to a type. ## Strict typing Strictly typed languages enforce typing on all data being interacted with. All data types strictly conform to standard JSON notations. In addition to data types being stricter, we also added types to various entities to ensure higher data consistency. ## Scores In API 2.0 the scores of a fixture are in the default API response. In API 3.0 this is not the case. For API 3 we've introduced the *`scores`* include. This has been added to retrieve a score for fixtures more conveniently. The include returns the scores per period and the current score for the regarding fixture. ## Participants vs localTeam & visitorTeam include This might be one of the most important model changes in API 3.0. Previously, `localTeam` and `visitorTeam` were the includes to use to get all team data. The previous includes are replaced by our new include: `participants.`From now on, this is the way to get information about the teams participating in a match. Both teams that play in the fixture are present in the participants array and their location is located in the meta section of a team. Below is an example of how a fixture with this new include can look.

Example

```json { "data": { "id": 18535517, "sport_id": 1, "league_id": 501, "season_id": 19735, "stage_id": 77457866, "group_id": null, "aggregate_id": null, "round_id": 274719, "state_id": 5, "venue_id": 8909, "name": "Celtic vs Rangers", "starting_at": "2022-09-03 11:30:00", "result_info": "Celtic won after full-time.", "leg": "1/1", "details": null, "length": 90, "placeholder": false, "last_processed_at": "2023-03-02 17:47:38", "has_odds": true, "starting_at_timestamp": 1662204600, "scores": [ { "id": 11316768, "fixture_id": 18535517, "type_id": 1, "participant_id": 53, "score": { "goals": 3, "participant": "home" }, "description": "1ST_HALF" }, { "id": 11316769, "fixture_id": 18535517, "type_id": 1, "participant_id": 62, "score": { "goals": 0, "participant": "away" }, "description": "1ST_HALF" }, { "id": 11316770, "fixture_id": 18535517, "type_id": 2, "participant_id": 53, "score": { "goals": 4, "participant": "home" }, "description": "2ND_HALF" }, { "id": 11316771, "fixture_id": 18535517, "type_id": 2, "participant_id": 62, "score": { "goals": 0, "participant": "away" }, "description": "2ND_HALF" }, { "id": 11316772, "fixture_id": 18535517, "type_id": 1525, "participant_id": 53, "score": { "goals": 4, "participant": "home" }, "description": "CURRENT" }, { "id": 11316773, "fixture_id": 18535517, "type_id": 1525, "participant_id": 62, "score": { "goals": 0, "participant": "away" }, "description": "CURRENT" } ], "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": "home", "winner": true, "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": "away", "winner": false, "position": 2 } } ], "periods": [ { "id": 4295921, "fixture_id": 18535517, "type_id": 1, "started": 1662204680, "ended": 1662207533, "counts_from": 0, "ticking": false, "sort_order": 1, "description": "1st-half", "time_added": 2, "period_length": 45, "minutes": null, "seconds": null }, { "id": 4296154, "fixture_id": 18535517, "type_id": 2, "started": 1662208498, "ended": 1662211318, "counts_from": 45, "ticking": false, "sort_order": 2, "description": "2nd-half", "time_added": 2, "period_length": 45, "minutes": null, "seconds": null } ] }, ```

## Rate limit per entity The rate limit will now be based on requests per entity instead of being based on a single endpoint. For example, the Team entity is used in Teams endpoints. You can find out more about the rate limit [here](/v3/api/rate-limit). ### Pagination A new pagination system has been implemented. In API 3.0, we will no longer provide a `count` and `total_pages` property in the meta of the response. Instead, you can paginate using the `has_more` parameter to determine if you can still propagate through results. This change decreases the load on our databases and massively increases API response speed and reliability. In addition to that it is now possible to add the *filters=populate* to your query parameter. This parameter allows for a higher pagination limit (max 1000), so you can populate your database more conveniently instead of using the default pagination limit of 50. To prevent our services from overloading, using includes is disabled when this filter is added to the request. Please check our [pagination tutorial ](/v3/tutorials-and-guides/tutorials/introduction/pagination)for more info. ### Livescores endpoints For API 2.0, we only had two live score endpoints. The “GET All Livescores” and “GET All In play Livescores”. The GET All Livescores endpoint gave all matches that would take place on that specific day, while the GET All In play Livescores endpoint would return all fixtures 15 minutes before they started. It will also disappear 15 minutes after the game is finished. For API 3.0, there are three live score endpoints available. The “GET Inplay Livescores”, “GET All Livescores”, and the “GET Latest Updated Livescores”. **The GET Inplay Livescores:** GET All Inplay Livescores: returns all the inplay fixtures. **GET All Livescores:** Returns the fixtures 15 minutes before the game starts. It will also disappear 15 minutes after the game is finished. **GET Latest Updated Livescores:** Returns all livescores that have received updates within 10 seconds. {% hint style="info" %} When you need the fixtures that will take place on a specific date, you can use the “GET Fixtures by Date” endpoint. This returns the fixtures from your requested date. {% endhint %} ## Core and odds [Core](https://docs.sportmonks.com/football2/v/core/) and [odds](https://docs.sportmonks.com/football2/v/odds/getting-started/welcome) are no longer sport specific. Both have their own documentation related to all sports released on API 3.0. Odds contain bookmakers and markets which are not sport specific but Odds are still available on a per sport basis. Bookmakers in API 3.0 have a different ID compared to API 2.0. To make migration easier, bookmakers that were also available in API 2.0 have a legacy\_id field, which contains the ID of this bookmaker in API 2.0. Please check our [tutorial on bookmakers](/v3/tutorials-and-guides/tutorials/odds-and-predictions/bookmakers#get-all-bookmakers) for more info. ## Statistics In API version 3 (V3), only recorded statistical values are returned in the response payload. This is a deliberate change from version 2 (V2), where unrecorded statistics were represented with a default value of zero. **What’s different in V3?** In V3, if an event or stat, such as a red card, has been recorded during a match, the corresponding value will be included in the API response. However, if no red card was issued in the match, that field will simply be **absent** from the response instead of returning `"redcards": 0` as was the case in V2. **Why was this change made?** This update is aimed at improving data integrity and clarity. By excluding fields for events that did not occur, the API avoids implying that a value of zero was definitively recorded. This is particularly relevant in cases where certain data might not have been tracked or confirmed, which could previously lead to misleading assumptions. ## Trends In API version 2, values in trends were for each team identifiable using only the minute of the recorded value, without a clear separation between periods, which could result in trends during injury time of the first half overlapping with the start of the second half. In version 3, all trend entities are listed within the same list and identifiable using the period, minute and participant (team). When a value is recorded during injury time, the minute and extra minute are added together. **Why was this change made?** This update is aimed at improving clarity and consistency through the API. Separation of the periods also prevents overlapping of values, which could show abnormal lines when showing trend graphs using version 2 data directly. For a deeper, tutorial-style explanation and examples of how to work with trend data in your integration, see the [Trends](/v3/tutorials-and-guides/tutorials/trends) page. # Syntax and filters ## Syntax The syntax for filtering and including works differently from API V2. The syntax is used across all endpoints: the documentation for each endpoint describes the exceptions regarding exclusions of some fields/relations. Find out everything about the new [syntax](/v3/api/syntax). ### Filters The filter system changed compared to the previous version. You can now select specific fields on the base entity or includes, and it’s possible to filter your request. Below is a fixture shown with events.

Example Fixture with Events

```javascript https://api.sportmonks.com/v3/football/fixtures/18535517?api_token=YOUR_TOKEN&include=events ``` ```javascript { "data": { "id": 18535517, "sport_id": 1, "league_id": 501, "season_id": 19735, "stage_id": 77457866, "group_id": null, "aggregate_id": null, "round_id": 274719, "state_id": 5, "venue_id": 8909, "name": "Celtic vs Rangers", "starting_at": "2022-09-03 11:30:00", "result_info": "Celtic won after full-time.", "leg": "1/1", "details": null, "length": 90, "placeholder": false, "last_processed_at": "2023-03-02 17:47:38", "has_odds": true, "starting_at_timestamp": 1662204600, "events": [ { "id": 42683644, "fixture_id": 18535517, "period_id": 4296154, "participant_id": 53, "type_id": 18, "section": "event", "player_id": 3298, "related_player_id": 10966261, "player_name": "Aaron Mooy", "related_player_name": "R. Hatate", "result": null, "info": null, "addition": null, "minute": 73, "extra_minute": null, "injured": false, "on_bench": false, "coach_id": null, "sub_type_id": null }, { "id": 42683195, "fixture_id": 18535517, "period_id": 4296154, "participant_id": 53, "type_id": 18, "section": "event", "player_id": 319282, "related_player_id": 9939171, "player_name": "Daizen Maeda", "related_player_name": "L. Abada", "result": null, "info": null, "addition": null, "minute": 73, "extra_minute": null, "injured": false, "on_bench": false, "coach_id": null, "sub_type_id": null }, { "id": 42703418, "fixture_id": 18535517, "period_id": 4296154, "participant_id": 62, "type_id": 19, "section": "event", "player_id": 2927, "related_player_id": null, "player_name": "Connor Goldson", "related_player_name": null, "result": null, "info": "Foul", "addition": "6th Yellow Card", "minute": 90, "extra_minute": null, "injured": null, "on_bench": false, "coach_id": null, "sub_type_id": null }, { "id": 42688034, "fixture_id": 18535517, "period_id": 4296154, "participant_id": 62, "type_id": 18, "section": "event", "player_id": 1452870, "related_player_id": 3387, "player_name": "F. Sakala", "related_player_name": "Ryan Kent", "result": null, "info": null, "addition": null, "minute": 78, "extra_minute": null, "injured": false, "on_bench": false, "coach_id": null, "sub_type_id": null }, //And more ```

As you can see in the response, you will receive all match events. But what if you’re only interested in a specific event like goals, cards or substitutions? You can filter on the specific data you're interested in. The URL now includes a `&filters` query parameter that shows the entity you want to filter on and the IDs you want to see in your results.

Example Fixture with Filtered Goal Events

```javascript https://api.sportmonks.com/v3/football/fixtures/18535517?api_token=YOUR_TOKEN&include=events&filters=eventTypes:14 ``` ```json { "data": { "id": 18535517, "sport_id": 1, "league_id": 501, "season_id": 19735, "stage_id": 77457866, "group_id": null, "aggregate_id": null, "round_id": 274719, "state_id": 5, "venue_id": 8909, "name": "Celtic vs Rangers", "starting_at": "2022-09-03 11:30:00", "result_info": "Celtic won after full-time.", "leg": "1/1", "details": null, "length": 90, "placeholder": false, "last_processed_at": "2023-03-02 17:47:38", "has_odds": true, "starting_at_timestamp": 1662204600, "events": [ { "id": 42688040, "fixture_id": 18535517, "period_id": 4296154, "participant_id": 53, "type_id": 14, "section": "event", "player_id": 173160, "related_player_id": null, "player_name": "David Turnbull", "related_player_name": null, "result": "4-0", "info": "Shot", "addition": "4th Goal", "minute": 78, "extra_minute": null, "injured": null, "on_bench": false, "coach_id": null, "sub_type_id": null }, { "id": 42646477, "fixture_id": 18535517, "period_id": 4295921, "participant_id": 53, "type_id": 14, "section": "event", "player_id": 9939171, "related_player_id": null, "player_name": "L. Abada", "related_player_name": null, "result": "1-0", "info": "Shot", "addition": "1st Goal", "minute": 8, "extra_minute": null, "injured": null, "on_bench": false, "coach_id": null, "sub_type_id": null }, //And more ```

So, we already explained how to use filters and how to filter on one particular ID. But what if you're interested in filtering on multiple IDs? That is also possible! You can use filters on multiple IDs.

Example Fixture with Filtered Events on multiple IDs

```javascript https://api.sportmonks.com/v3/football/fixtures/18842556?api_token=YOUR_TOKEN&include=events.type&filters=eventTypes:14,18 ``` {% code fullWidth="false" %} ```json { "data": { "id": 18842556, "sport_id": 1, "league_id": 8, "season_id": 21646, "stage_id": 77464011, "group_id": null, "aggregate_id": null, "round_id": 307169, "state_id": 5, "venue_id": 230, "name": "Liverpool vs Manchester City", "starting_at": "2024-03-10 15:45:00", "result_info": "Game ended in draw.", "leg": "1/1", "details": null, "length": 90, "placeholder": false, "has_odds": true, "starting_at_timestamp": 1710085500, "events": [ { "id": 108388309, "fixture_id": 18842556, "period_id": 5277498, "participant_id": 9, "type_id": 14, "section": "event", "player_id": 982, "related_player_id": 1371, "player_name": "John Stones", "related_player_name": "Kevin De Bruyne", "result": "0-1", "info": "Shot", "addition": "1st Goal", "minute": 23, "extra_minute": null, "injured": null, "on_bench": false, "coach_id": null, "sub_type_id": 1522, "type": { "id": 14, "name": "Goal", "code": "goal", "developer_name": "GOAL", "model_type": "event", "stat_group": null } }, { "id": 108406572, "fixture_id": 18842556, "period_id": 5277705, "participant_id": 8, "type_id": 18, "section": "event", "player_id": 30062, "related_player_id": 6013424, "player_name": "Cody Gakpo", "related_player_name": "Darwin Núñez", "result": null, "info": null, "addition": null, "minute": 76, "extra_minute": null, "injured": false, "on_bench": false, "coach_id": null, "sub_type_id": 1523, "type": { "id": 18, "name": "Substitution", "code": "substitution", "developer_name": "SUBSTITUTION", "model_type": "event", "stat_group": null } }, { "id": 108400368, "fixture_id": 18842556, "period_id": 5277705, "participant_id": 9, "type_id": 18, "section": "event", "player_id": 34594, "related_player_id": 159142, "player_name": "Stefan Ortega", "related_player_name": "Ederson", "result": null, "info": null, "addition": null, "minute": 56, "extra_minute": null, "injured": true, "on_bench": false, "coach_id": null, "sub_type_id": 1524, "type": { "id": 18, "name": "Substitution", "code": "substitution", "developer_name": "SUBSTITUTION", "model_type": "event", "stat_group": null } }, { "id": 108405790, "fixture_id": 18842556, "period_id": 5277705, "participant_id": 8, "type_id": 18, "section": "event", "player_id": 1078, "related_player_id": 37316835, "player_name": "Andrew Robertson", "related_player_name": "Conor Bradley", "result": null, "info": null, "addition": null, "minute": 61, "extra_minute": null, "injured": false, "on_bench": false, "coach_id": null, "sub_type_id": 1523, "type": { "id": 18, "name": "Substitution", "code": "substitution", "developer_name": "SUBSTITUTION", "model_type": "event", "stat_group": null } }, ``` {% endcode %}

More information and a more detailed explanation are covered on our [request options page.](/v3/api/request-options) ### Select the fields you need You can request only the fields you need by using the new [syntax](/v3/api/syntax). Filters can filter the data based on the fields you would like to display in your application. `:` can be used for filtering the fields you want to see in the response. For example, you only want the name of a certain team. In this case you need to use `participants:name`. ## Custom Sorting You can use custom sorts on endpoints; this enables the sorting of base entities returned in the endpoint responses. This feature is designed to enhance flexibility and customisation for users interacting with the API. ### Usage This provides users with the ability to customise sorting of returned data through the use of the `sortBy` and `order` parameters. This functionality is particularly useful when retrieving lists of fixtures in football, as it allows users to organise the data based on specific criteria. **Sorting Fixtures** When querying fixtures, users can specify the field to sort by and the desired order using the following parameters: * **sortBy**: Specifies the field by which the data will be sorted. Currently supported fields include `starting_at` and `name`. * **order**: Determines the order in which the data will be sorted. Users can choose between ascending (`asc`) and descending (`desc`) orders. ### Examples **Sort by `starting_at`**: This option sorts the fixtures based on their starting date and time. ```bash https://api.sportmonks.com/v3/football/fixtures&sortBy=starting_at&order=desc ``` This URL sorts the fixtures in descending order of their starting date and time. **Sort by `name`**: This option sorts the fixtures alphabetically based on their names. ```bash https://api.sportmonks.com/v3/football/fixtures&sortBy=name&order=asc ``` This URL sorts the fixtures alphabetically by their names in ascending order. {% hint style="info" %} Sorting on the `name` field currently works for all entities with a `"name"` field. For Fixtures, sorting also works on the `starting_at` field. {% endhint %} {% hint style="danger" %} If an unsupported field is passed to sort on, an error is thrown, and the request returns a 400 Bad Request HTTP code. {% endhint %} A more detailed explanation is covered on our [request options page](/v3/api/request-options) # New endpoints and data features Thanks to our new back-end structure, we can offer more data features and new endpoints. (i.e. ball coordinates, referee and coach statistics) ### New Endpoints * [Transfer endpoints](/v3/endpoints-and-entities/endpoints/transfers) * [All Transfers](/v3/endpoints-and-entities/endpoints/transfers/get-all-transfers) * [Latest Transfers](/v3/endpoints-and-entities/endpoints/transfers/get-latest-transfers) * [Transfer By ID](/v3/endpoints-and-entities/endpoints/transfers/get-transfer-by-id) * [Transfers By Team ID](/v3/endpoints-and-entities/endpoints/transfers/get-transfers-by-team-id) * [Transfers By Player ID](/v3/endpoints-and-entities/endpoints/transfers/get-transfers-by-player-id) * [Referees endpoints](/v3/endpoints-and-entities/endpoints/referees) * [All Referees](/v3/endpoints-and-entities/endpoints/referees/get-all-referees) * [Referee By ID](/v3/endpoints-and-entities/endpoints/referees/get-referee-by-id) * [Referees By Country ID](/v3/endpoints-and-entities/endpoints/referees/get-referees-by-country-id) * [Search Referee By Name](/v3/endpoints-and-entities/endpoints/referees/get-referees-search-by-name) * [Schedules endpoints](/v3/endpoints-and-entities/endpoints/schedules) * [Schedules By Season ID](/v3/endpoints-and-entities/endpoints/schedules/get-schedules-by-season-id) * [Schedules By Season and Team ID](/v3/endpoints-and-entities/endpoints/schedules/get-schedules-by-season-id-and-team-id) * Search endpoints for all entities with a name field * Extra endpoints for each entity * All endpoints for most entities **Available in core:** * Base entities; * Continents * Regions * Countries * Cities * Filters * Types endpoint * All Types * Type By ID * My endpoints (to check your own data features) * Data Features endpoint * My Data Features * Endpoints * My Endpoints * Leagues * My Leagues * Search endpoints for all entities with a name field * Extra endpoints for each entity ### League priority You can now prioritize the leagues you want to view. In [MySportmonks](https://my.sportmonks.com/api/leagues/priority) you can change the priority of all leagues in your subscription. You can simply sort them according to your liking, and the API will show leagues in this specific order when requesting leagues. ### New Data Features * Offsides events for major leagues * Detailed player positions * Shots on/off target events for major leagues * Placeholder games available (finals, etc) * Ball coordinates (semi-live) * Forecast weather report * Expanded predictions * Predictive lineups * Coach statistics * Referee statistics * Period statistics * More statistics in general * League priority configuration # Authentication All of our APIs require authentication. You can create API tokens in MySportmonks. To make our first request, we’ll need to get authenticated first. We offer two different options for passing your API token. You are free to choose between the authentication methods. You can also use both of them at the same time. Please note that both methods count towards the same rate-limiting. * **Authenticate using a query parameter**\ You can pass your API token by passing 'api\_token' in your request parameters, like so: ```http https://api.sportmonks.com/api/v3/football/livescores?api_token=YOUR_TOKEN ``` * **Authenticate using a request header**\ You can also pass your token via an 'Authorisation' header, like so:

Header	Value
Authorization	`YOUR_TOKEN`

### How to create a new API Token in MySportmonks You can obtain and manage your API token in [**MySportmonks.**](https://my.sportmonks.com/api/tokens) The API token is intended for your eyes only and, as such, should be stored securely. Our tokens have no expiration date and will remain valid until you manually delete them yourself. Follow these simple steps to generate your API token: 1. Log in to[ MySportmonks](https://my.sportmonks.com/). \ If you do not have an account, you can create one using this link: 2. Go to the API section in your dashboard. A dropdown will unfold; select 'Tokens'. 3. Enter a name for your new token in the 'Token name' field. 4. Click the "Create" button.\ \

5. Your new API token will be generated instantly and ready to use! Note: Be sure to store your token securely after it has been created. For security reasons, it will not be shown again or stored in MySportmonks. ### Error codes When making a request, a code response will always be returned. The following are all possible HTTP response codes for any request made to the API: | Code | Description | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **200: OK** | Request succeeded | | **400: Bad Request** | It seems that some part of the request is malformed. The exact reason is returned in the response. | | **401: Unauthorized** | The request is not authenticated. | | **403: Forbidden** | Not authorized. Indicates you're attempting to access a feed that is not accessible from your plan. | | **429: Too Many Requests** | Too many requests. In order to make the API as responsive as possible, you have an hourly request limit. The limit for your current subscription can be found in any successful response. Check the "meta" section to find out your limit. | | **500: Internal Server Error** |

An internal error has occurred and has been logged for further inspection. Please email support if you are receiving this error.

Check our status page to see if we are aware of any possible issues

| {% hint style="danger" %} Directly integrating an API into the frontend of a web application can be risky as it can expose sensitive information, such as your Sportmonks API token, to potential security breaches. {% endhint %} To avoid this, it is best practice to use a middleware, such as a backend or proxy server, to handle all communication between the frontend and the API. This middleware acts as an intermediary, making sure your API tokens are stored securely and not exposed to users. Using middleware makes it much harder for malicious actors to access sensitive information, keeping your application more secure overall. # Making your first request Now that all prerequisites have been fulfilled, we’re ready to send our first request to the API! {% hint style="info" %} Before being able to make a request, you need to create your account in [MySportmonks](https://docs.sportmonks.com/v3/welcome/www.my.sportmonks.com). Here you can create your personal API token, which you need to [authenticate](/v3/welcome/authentication) your requests. You can use the free plan or choose one of the various plans and data features of Sportmonks. {% endhint %} ## Build the request The request consists of the following components: * The base URL * A path parameter, in this example, we use *fixtures* * Optional: Query string parameters, to filter on enrich your requests. * And finally, your API token ### The base URL In this example we're using the [fixtures endpoint](/v3/endpoints-and-entities/endpoints/fixtures). The base URL of the fixtures endpoint is:

https://api.sportmonks.com/v3/football

### Your API token We offer two different options for passing your API token. You are free to choose between the authentication methods. You can also use both of them at the same time. Please note that both methods count towards the same [rate-limiting.](/v3/api/rate-limit) **Authenticate using a query parameter:**\ You can pass your API token by passing 'api\_token' in your request parameters, like so: \ `https://api.sportmonks.com/v3/football?api_token=YOUR_TOKEN` **Authenticate using a request header:**\ You can also pass your token via an 'Authorization' header, like so:

Header	Value
Authorization	`YOUR_TOKEN`

For example, this can results in the below request and response: ```javascript https://api.sportmonks.com/v3/football/fixtures?api_token=YOUR_TOKEN ```

Basic response

The example above was the most basic request you can create, while our highly flexible football API 3.0 can handle way more advanced requests. Our API's data will enable you to create excellent and specialized applications. Let’s make another request, and add an include to get more information. The includes can be found on the specific endpoint page. In our case, [fixtures](/v3/endpoints-and-entities/endpoints/fixtures). {% code overflow="wrap" %} ```javascript https://api.sportmonks.com/v3/football/fixtures?api_token=YOUR_TOKEN&include=statistics ``` {% endcode %} You are getting the hang of it now. Let’s make one more request with multiple includes. {% code overflow="wrap" %} ```javascript https://api.sportmonks.com/v3/football/fixtures?apitoken=YOUR_TOKEN&include=statistics;events ``` {% endcode %} {% hint style="info" %} Are you interested in seeing the difference in response when you use includes vs when you don't? Check the below response examples.

Response without includes

Response with includes

{% endhint %} ## API Syntax Great, now you have used the first part of API 3.0’s [syntax.](/v3/api/syntax) A quick overview of the new syntax:

Syntax	Usage	Example
`&select=`	Select specific fields on the base entity	`&select=name`
`&include=`	Include relations	`&include=lineups`
`&filters=`	Filter your request	`&filters=eventTypes:15`
`;`	Mark end of (nested) relation. You can start including other relations from here	`&include=lineups;events;participants`
`:`	Mark field selection	`&include=lineups:player_name;events:player_name,related_player_name,minute`
`,`	Used as separation to select or filter on more ids	`&include=events:player_name,related_player_name,minute&filters=eventTypes:15`

### **Request: use multiple include** For example, you want the teams and events of a certain fixture. In this case, you would use `participants;events` {% code overflow="wrap" %} ```javascript https://api.sportmonks.com/v3/football/fixtures?api_token=YOUR_TOKEN&include=participants;events ``` {% endcode %}

Response

```javascript { "data": [ { "id": 17948776, "sport_id": 1, "league_id": 271, "season_id": 17328, "stage_id": 77448541, "group_id": null, "aggregate_id": null, "round_id": 240936, "state_id": 5, "venue_id": 339977, "name": "AGF vs Randers", "starting_at": "2021-04-22 15:45:00", "result_info": null, "leg": "1/1", "details": null, "length": 90, "placeholder": false, "last_processed_at": "2023-01-13 14:16:47", "starting_at_timestamp": 1619106300, "participants": [ { "id": 2905, "sport_id": 1, "country_id": 320, "venue_id": 1708, "gender": "male", "name": "AGF", "short_code": "AGF", "image_path": "https://cdn.sportmonks.com/images/soccer/teams/25/2905.png", "founded": 1902, "type": "domestic", "placeholder": false, "last_played_at": "2023-01-19 14:00:00", "meta": { "location": "home" } }, { "id": 2356, "sport_id": 1, "country_id": 320, "venue_id": 318820, "gender": "male", "name": "Randers", "short_code": "RDF", "image_path": "https://cdn.sportmonks.com/images/soccer/teams/20/2356.png", "founded": 2003, "type": "domestic", "placeholder": false, "last_played_at": "2022-11-13 19:00:00", "meta": { "location": "away" } } ], "events": [ { "id": 2255893, "fixture_id": 17948776, "period_id": 20128, "participant_id": 2905, "type_id": 18, "section": "event", "player_id": 84471, "related_player_id": 151549, "player_name": "Alexander Munksgaard", "related_player_name": "Alex Gersbach", "result": null, "info": null, "addition": null, "minute": 32, "extra_minute": null, "injured": true, "on_bench": false, "coach_id": null, "sub_type_id": null }, //and more! ```

### Request: only select a specific field One of our new additions to API 3.0 is a name field on the fixtures. The name field contains a textual representation of the participants playing the fixture. Without selecting a specific field, the API request and response would look like this: ```javascript https://api.sportmonks.com/v3/football/fixtures/18535517?api_token=YOUR_TOKEN ```

Response

As you can see, the API response is rather large if you're only interested in the fixture's name. Let's select that API field to reduce the response length and size. We're using the [fixtures endpoint](/v3/endpoints-and-entities/endpoints/fixtures). This means we can select on all the fields of the [fixtures entity.](/v3/endpoints-and-entities/entities/fixture#fixture) You can do this by adding `&select=`{specific fields on the base [entity](/v3/endpoints-and-entities/entities)}. In our example, this would result in the below API request and response: {% code overflow="wrap" %} ```javascript https://api.sportmonks.com/v3/football/fixtures/18535517?api_token=YOUR_TOKEN&select=name ``` {% endcode %}

Response

```javascript { "data": { "name": "Celtic vs Rangers", "id": 18535517, "sport_id": 1, "round_id": 274719, "stage_id": 77457866, "group_id": null, "aggregate_id": null, "league_id": 501, "season_id": 19735, "venue_id": 8909, "state_id": 5, "starting_at_timestamp": null }, ```

As you can see in the example response above, the 'name' field is only returned for the fixture. {% hint style="info" %} Please note that the fields that have relations are also automatically included for technical reasons. {% endhint %} ### Request: filter your request Next to selecting specific fields on the base entity or includes, it’s possible to filter your request. Let’s say you want to request all the events of a specific fixture, like Celtic vs Rangers. Your request would look like this: {% code overflow="wrap" %} ```javascript https://api.sportmonks.com/v3/football/fixtures/18535517?api_token=YOUR_TOKEN&include=events ``` {% endcode %}

Response

As you can see in the response, you will receive all match events. But what if you’re only interested in a specific event like goals, cards or substitutions? **You can filter on the specific data you're interested in:** {% code overflow="wrap" %} ```javascript https://api.sportmonks.com/v3/football/fixtures/18535517?api_token=YOUR_TOKEN&include=events&filters=eventTypes:18 ``` {% endcode %}

Response

```javascript { "data": { "id": 18535517, "sport_id": 1, "league_id": 501, "season_id": 19735, "stage_id": 77457866, "group_id": null, "aggregate_id": null, "round_id": 274719, "state_id": 5, "venue_id": 8909, "name": "Celtic vs Rangers", "home_score": 4, "away_score": 0, "starting_at": "2022-09-03 11:30:00", "result_info": "Celtic won after full-time.", "leg": "1/1", "details": null, "length": 90, "placeholder": false, "starting_at_timestamp": 1662204600, "events": [ { "id": 42645216, "fixture_id": 18535517, "period_id": 4295921, "participant_id": 53, "type_id": 18, "section": "event", "player_id": 108471, "related_player_id": 460810, "player_name": "Georgios Giakoumakis", "related_player_name": "Kyogo Furuhashi", "result": null, "info": null, "addition": null, "minute": 5, "extra_minute": null, "injured": true, "on_bench": false }, { "id": 42666547, "fixture_id": 18535517, "period_id": 4296154, "participant_id": 62, "type_id": 18, "section": "event", "player_id": 172985, "related_player_id": 10504, "player_name": "Scott Wright", "related_player_name": "Glen Kamara", "result": null, "info": null, "addition": null, "minute": 46, "extra_minute": null, "injured": false, "on_bench": false }, { "id": 42687449, "fixture_id": 18535517, "period_id": 4296154, "participant_id": 62, "type_id": 18, "section": "event", "player_id": 172394, "related_player_id": 3262, "player_name": "Ryan Jack", "related_player_name": "John Lundstram", "result": null, "info": null, "addition": null, "minute": 78, "extra_minute": null, "injured": false, "on_bench": false }, { "id": 42688034, "fixture_id": 18535517, "period_id": 4296154, "participant_id": 62, "type_id": 18, "section": "event", "player_id": 1452870, "related_player_id": 3387, "player_name": "Fashion Sakala", "related_player_name": "Ryan Kent", "result": null, "info": null, "addition": null, "minute": 78, "extra_minute": null, "injured": false, "on_bench": false }, { "id": 42675143, "fixture_id": 18535517, "period_id": 4296154, "participant_id": 62, "type_id": 18, "section": "event", "player_id": 92276, "related_player_id": 32026, "player_name": "Alfredo Morelos", "related_player_name": "Antonio Colak", "result": null, "info": null, "addition": null, "minute": 60, "extra_minute": null, "injured": false, "on_bench": false }, { "id": 42675290, "fixture_id": 18535517, "period_id": 4296154, "participant_id": 62, "type_id": 18, "section": "event", "player_id": 1442, "related_player_id": 23277869, "player_name": "Scott Arfield", "related_player_name": "Malik Tillman", "result": null, "info": null, "addition": null, "minute": 60, "extra_minute": null, "injured": false, "on_bench": false }, { "id": 42682889, "fixture_id": 18535517, "period_id": 4296154, "participant_id": 53, "type_id": 18, "section": "event", "player_id": 173160, "related_player_id": 1494712, "player_name": "David Turnbull", "related_player_name": "Matt O'Riley", "result": null, "info": null, "addition": null, "minute": 72, "extra_minute": null, "injured": false, "on_bench": false }, { "id": 42683195, "fixture_id": 18535517, "period_id": 4296154, "participant_id": 53, "type_id": 18, "section": "event", "player_id": 319282, "related_player_id": 9939171, "player_name": "Daizen Maeda", "related_player_name": "Liel Abada", "result": null, "info": null, "addition": null, "minute": 73, "extra_minute": null, "injured": false, "on_bench": false }, { "id": 42683644, "fixture_id": 18535517, "period_id": 4296154, "participant_id": 53, "type_id": 18, "section": "event", "player_id": 3298, "related_player_id": 10966261, "player_name": "Aaron Mooy", "related_player_name": "Reo Hatate", "result": null, "info": null, "addition": null, "minute": 73, "extra_minute": null, "injured": false, "on_bench": false }, { "id": 42673138, "fixture_id": 18535517, "period_id": 4296154, "participant_id": 53, "type_id": 18, "section": "event", "player_id": 1494701, "related_player_id": 190919, "player_name": "Moritz Jenz", "related_player_name": "Carl Starfelt", "result": null, "info": null, "addition": null, "minute": 56, "extra_minute": null, "injured": true, "on_bench": false } ] }, ```

### Next steps: Optimise your requests You've made your first API request, great start! But there's much more you can do to make your requests more powerful and efficient. Right now, you're getting all the data available for that endpoint. In the real world, you'll often want to: * **Get only the data you need** (reduce response size and speed) * **Filter results** (only matches from a specific league, date range, etc.) * **Include related data** (player info, match events, statistics, all in one request) * **Sort and organise** results exactly how your app needs them Learn how to do all of this and more with our comprehensive **Request Options** guide. It shows you exactly how to fine-tune every API call to retrieve precisely what your application needs. [Explore Request Options →](https://docs.sportmonks.com/football/api/request-options) # Best practices Our API provides well-structured responses with strictly typed entities, such as statistics and lineups. This page provides best practices for using our data effectively in sports applications. ### Initial data load & syncing strategy Most of our endpoints support pagination, so you’ll often need multiple requests to retrieve full datasets. To streamline this, we provide features and patterns designed for scalability and consistency. **Bulk fetch with `filters=populate`** * Use `filters=populate` on endpoints to disable all includes. This ensures the response payload is minimal (no extra nested data) and enables a **page size of 1000** records, reducing the total number of pages. * Because includes are disabled, you'll fetch only the base entity fields (no heavy relational joins). * **Pro tip**: For your initial sync, use `filters=populate` to bootstrap your dataset quickly and with fewer API calls. **Incremental sync with `idAfter`** Once your initial dataset is established, keep your database up to date using the `idAfter` filter: * Use a parameter like `filters=idAfter:12345` to fetch only those records whose IDs are **greater than** the last known ID. * Combine this with `filters=populate` to keep responses lightweight. * This strategy ensures you're only pulling new entries, not re-fetching old ones. **Developer notes & examples** * **Concurrent paging**: After fetching page 1 with `idAfter` & `populate`, you can fetch pages 2, 3, etc., in parallel (within your rate-limit constraints) to speed up initial sync. * **Example (pseudocode for bulk + incremental)**: ```javascript // Step 1: bulk load all via pages for (let page = 1; ; page++) { let resp = await fetchEndpoint({ include: null, filters: `populate;page:${page}` }) if (!resp.data.length) break saveToDb(resp.data) } // Step 2: start incremental sync loop let lastMaxId = getMaxIdFromDb() setInterval(async () => { let resp = await fetchEndpoint({ include: null, filters: `populate;idAfter:${lastMaxId}` }) if (resp.data.length) { saveToDb(resp.data) lastMaxId = getMaxIdFromDb() } }, pollIntervalMs) ``` * **Edge case (out-of-order IDs)**: In rare cases, data might arrive with IDs not strictly increasing (e.g. a delayed update or backfill). It’s good to *also* run periodic full sync (snapshot) of reference entities to catch anomalies. * **Empty result handling**: If your `idAfter` call returns no data (empty), don’t panic, it means there’s nothing new. But if you see long streaks with nothing, consider switching to a slower polling or check connectivity. **Pitfalls & tips** * **Watch for rate limits**: Bulk + parallel requests can accidentally hit your limits. Always space out your calls or batch smartly. * **New vs updated vs deleted**: `idAfter` only handles *new* records (or records with new IDs). It does not detect updates to existing ones or deletions. Use other filters (e.g. `IsDeleted` or “latest update” endpoints) to catch those. * **Combine strategies**: Use multiple sync strategies in tandem, initial bulk, incremental fetch, “latest updated” polls, and occasional full snapshot reconciliation. * **Monitoring**: Log how many new records you get per sync, and detect decreasing yields (i.e. when little new data is arriving), that may indicate everything is in sync. ### Reducing includes and response data Our API supports optional **includes** (nested related entities) to enrich responses. But excessive includes increase payload size, latency, and bandwidth usage. To optimize performance, we strongly recommend caching certain entities on your side so you can avoid requesting includes unnecessarily. **Entities we recommend caching** These are entities that rarely change and are safe to cache: * States * Types * Continents * Countries * Regions * Cities By caching these, you can often eliminate half or more of your includes, trimming response size and speeding your requests. **How to use cached entities instead of includes** 1. **At startup or periodically**, fetch and store the full lists of the above entities from endpoints like `/states`, `/types`, `/countries`, etc. 2. In your application logic, when you receive an object with a `type_id`, `region_id`, etc., look it up in your local cache instead of asking the API to include the full object. 3. Only request includes when you need deep details (e.g. nested objects or rarely updated relations). **Example: caching “Types” to skip includes** Suppose a match entity has a field `type_id` pointing to a “match type” (e.g. league, cup, friendly). You can do this: * During app startup (or daily), call `/types` and cache all type records (ID → full type object). * When fetching fixtures or matches, **omit** `include=type` (or remove it) and rely on your local cache to resolve `type_id` to the developer\_name of the type. * Only if you see a `type_id` not in your cache, you can fetch `/types/{id}` once to update your cache. This avoids bloating every match response with full type objects. **Developer tips & caveats** * **TTL & refresh strategy:** Since these entities change rarely, you can assign a long TTL (e.g. a few hours or a day) and refresh them periodically (cron job, background task). * **Invalidation:** If your cache has stale entries (e.g. a country name changes), you should detect and refresh. A simple strategy: always check for unknown IDs or version mismatches and fetch fresh data when needed. * **Fallback includes:** In edge cases (e.g. a new region not yet in cache), you can still request the include for that one record to fill your cache. * **Monitor cache hit rate:** Track how often your cached lookup resolves vs missing. A high hit rate means your design is effective. * **Size limits:** These entities are generally small (hundreds to a few thousands of records), so caching them in memory or fast stores (Redis, in-app store) is cheap. **Impact & benefits** * **Reduced bandwidth & latency**: Smaller JSON payloads travel over the wire faster. * **Lower API load**: You reduce work on the server by omitting heavy joins/includes. * **Simpler client logic**: You have control over which related data you load and when. ### Avoiding request timeouts Some endpoints can return very large payloads depending on how many includes you attach and how much live activity is happening at the time. The livescores endpoint is the most variable, during a busy match window, a single enriched request can grow large enough to time out before it completes, even under normal infrastructure conditions. The sections below explain what drives this and how to structure your requests to avoid it. #### Why livescore requests time out Response size compounds quickly on the livescores endpoint. Each additional include adds data for every active fixture in the response. The two biggest contributors are: * **`trends.type`** : starts at a similar size to statistics but grows as each match progresses, since trends accumulate over the course of the game. Including `.type` on top of this expands the payload further and increases server processing time. * **`lineups.details`** and **`periods.statistics`** : both are nested includes that multiply in size across many concurrent fixtures. Late-minute fixtures are particularly heavy because they have accumulated the most data. When several late-minute fixtures are live at the same time as early-minute ones receiving new events, a single enriched livescores request is at its highest risk of timing out. #### Recommendations **Cache types and states locally** Types and states are mostly static. Fetch them once at startup and store them in your application database or cache. When you resolve a `type_id` or `state_id` locally, you can remove `.type` and `states` from your includes entirely, which significantly reduces both response size and server load. See **Reducing includes and response data** above for the full caching strategy. **Split heavy includes into separate requests** Rather than fetching everything in one livescores call, split includes that update on a different cadence into their own requests. Trends are a good example. New trends are stored just after the start of each minute, so there is no benefit to fetching them on every livescores poll. Instead: * Poll the livescores endpoint (with scores, events, participants) at your normal interval. * Schedule a separate trends request once per minute, offset by 30 seconds past the minute mark to ensure new data is available. This reduces the size of your main polling request and keeps the trends fetch lean and predictable. The same principle applies to `lineups.details` and `periods.statistics`. Both update infrequently relative to scores and events, so fetching them separately on a slower interval is more efficient than including them on every poll. **Example: splitting livescores from trends** ```javascript const apiToken = 'YOUR_API_TOKEN'; const leagueFilter = 'fixtureLeagues:8'; // Main poll — scores and events only, every 10 seconds async function pollLivescores() { const r = await fetch( `https://api.sportmonks.com/v3/football/livescores/latest?api_token=${apiToken}&include=scores;events;participants&filters=${leagueFilter}` ); const data = await r.json(); updateScoreboard(data.data); } // Trends poll — separate, once per minute at the 30-second mark async function pollTrends() { const r = await fetch( `https://api.sportmonks.com/v3/football/livescores/inplay?api_token=${apiToken}&include=trends&filters=${leagueFilter}` ); const data = await r.json(); updateTrends(data.data); } // Start main polling setInterval(pollLivescores, 10000); // Start trends polling — offset 30 seconds past each minute const now = new Date(); const msUntilNextMinute = (60 - now.getSeconds()) * 1000 - now.getMilliseconds(); const msUntil30SecMark = msUntilNextMinute + 30000; setTimeout(() => { pollTrends(); // first run setInterval(pollTrends, 60000); // then every minute }, msUntil30SecMark); ``` **Summary of includes to treat with care on livescores** | Include | Risk | Recommendation | | ------------------------------------------ | ------------------------------------------- | ------------------------------------------------------------ | | `trends.type` | High, grows per match, per minute | Cache types locally; fetch trends separately once per minute | | `trends` | Medium , grows as matches progress | Fetch separately on a 60-second interval | | `lineups.details` | Medium , nested, multiplies across fixtures | Fetch separately; lineups rarely change mid-match | | `periods.statistics` | Medium , nested per period per fixture | Fetch separately or on demand per fixture | | `statistics.type` / `.type` on any include | High , expands every stat object | Always cache types locally and remove `.type` from includes | ### CORS (Cross-Origin Resource Sharing) When building client-side (browser) applications that call the Sportmonks API, you may see an error like: > “Request from origin has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource” This happens because browsers enforce the **same-origin policy**, which prevents JavaScript from making requests to a different domain unless explicitly allowed. You are calling the API directly from the front end, and since it is a different origin, the API must permit it. #### Why this is risky + best practice Direct frontend integration may expose sensitive data, especially your API token to end users. To avoid this risk and to handle CORS properly, use a **middleware layer** (backend or proxy) as an intermediary: * The frontend sends requests to your middleware. * The middleware attaches your API token securely and forwards the request to the Sportmonks API. * The middleware returns the API response to the frontend, with correct CORS headers. * This setup ensures your token is never exposed in client-side code. Using such a proxy makes it much harder for malicious actors to access your credentials or misuse your API. #### How CORS works in brief 1. The browser adds an `Origin` header in requests to indicate where the request is coming from. 2. For certain methods or headers, the browser first sends a **preflight OPTIONS** request. 3. The server must respond with appropriate headers like `Access-Control-Allow-Origin`, `Access-Control-Allow-Methods`, `Access-Control-Allow-Headers`. 4. If those headers permit the request, the browser proceeds; otherwise it blocks it. #### Developer tips & examples **Specifying allowed origins** Do **not** use `*` (wildcard) in `Access-Control-Allow-Origin` once in production if your API uses credentials (cookies, auth headers). Instead, allow specific origins: ```http Access-Control-Allow-Origin: https://my-frontend.com Access-Control-Allow-Methods: GET, POST, OPTIONS Access-Control-Allow-Headers: Content-Type, Authorization ``` If you allow credentials (`Access-Control-Allow-Credentials: true`), the `Allow-Origin` must be an explicit origin, not `*`. **Handling preflight (OPTIONS) requests** For any non-simple request (e.g. custom headers or methods like PUT), the browser first sends an OPTIONS request. Your server (or middleware) needs to correctly answer: ```http OPTIONS /api/endpoint HTTP/1.1 Origin: https://my-frontend.com Access-Control-Request-Method: POST Access-Control-Request-Headers: Content-Type, Authorization ``` Response should include: ```http HTTP/1.1 200 OK Access-Control-Allow-Origin: https://my-frontend.com Access-Control-Allow-Methods: GET, POST, OPTIONS Access-Control-Allow-Headers: Content-Type, Authorization Access-Control-Allow-Credentials: true Access-Control-Max-Age: 3600 ``` That tells the browser it is safe to send the actual request. #### Common pitfalls & security notes * Avoid using `*` for `Access-Control-Allow-Origin` in production, especially when credentials are involved. * Ensure even error responses include proper CORS headers, if they don’t, the browser may hide error details. * Regularly audit which origins you allow. As your app evolves, remove unused or outdated domains. * Remember: CORS is enforced by browsers only. Non-browser clients (e.g. mobile apps, server-to-server) are not restricted by CORS. ### **Rate Limiting** To ensure fair usage and maintain optimal performance for all users, adhere to our rate limiting policies: * Familiarise yourself with our API’s rate limits and throttle your requests to avoid exceeding them. Exceeding limits may lead to temporary restrictions or suspension of access. * Implement client-side rate limiting to prevent bursts of requests from overwhelming our servers. By observing reasonable request frequencies, you help maintain a smooth experience for all. Below are deeper explanations, patterns, and examples to help you build an effective rate-limiting layer. **Why client-side rate limiting matters** Even though the API enforces limits, relying solely on that enforcement results in: * Unexpected `429 Too Many Requests` errors * Jitter or latency spikes * Poor predictability under load By proactively controlling your request velocity, you reduce failed calls and improve stability. Many systems use client-side throttling for exactly this reason. **Common rate-limiting algorithms** Choosing the right algorithm affects how smooth your request pattern is. [Some standard approaches](https://www.sportmonks.com/glossary/api-rate-limit/): * **Fixed window**: Count requests per fixed time interval (e.g. max 100 per minute). Simple, but bursty at window boundaries. * **Sliding window**: Keeps a rolling window of time, smoothing out burst edges. * **Token bucket**: Tokens are refilled at a steady rate; each request “costs” a token. Allows bursts if tokens are available. * **Leaky bucket**: Requests queue up and are processed at a constant rate; excess requests “leak” out or are dropped. Often a token bucket or sliding window is a good fit for API clients. **Handling `429` and backoff** Even with client-side throttling, you may still hit rate limits (e.g. under concurrency or traffic shifts). Handle `429` responses gracefully: * Check for a `Retry-After` header, if provided, and wait that duration. * Use **exponential backoff** (with jitter) on repeated failures: e.g. wait 0.5s, then 1s, then 2s, etc. * Cap the maximum backoff delay and eventually give up or notify the user. * After backing off, resume a conservative request rate rather than jumping back to full speed. **Best practices & tips** * Use analytics / monitoring to track how often you hit the rate limit, to tune your client-side throttling thresholds. * If your app makes multiple types of API calls (e.g. livescores vs historical data), allocate separate rate buckets or priorities. * During low traffic periods, you can increase throughput; during peaks, be conservative. * Log request metadata (endpoint, timestamp) to help debugging when limits are hit. * Use jitter (random small variation) in backoff timing to avoid synchronized retries across many clients. ### **Optimised querying & filtering** You should aim to retrieve *just what you need,* not entire datasets with lots of unused fields. Using filters and caching intelligently can yield more efficient, faster, and cheaper requests. **Using filters effectively** * Whenever possible, apply server-side filtering over retrieving everything and filtering client-side. This reduces response size and network waste. * Use field filters (e.g. `status=active`, `season_id=2025`) or property filters (e.g. `score_gt`, `date_lt`) if supported. * Combine filters to narrow results (logical AND) rather than fetching then discarding. * Be cautious when using filters around boundary values (dates, times), test edge cases (e.g. matches exactly at midnight). * Consider ordering your filters so the “cheapest / most selective” ones run first (i.e. filter by competition before filtering by team, etc.) **Caching query results & lookups** Because many queries are repetitive or stable over time, you can cache responses or lookup tables to avoid re-fetching the same data. * **Cache lookups of commonly accessed entities** (e.g. teams, types, leagues). If your data model has `team_id` or `type_id`, you can resolve it locally rather than requesting `include=team` or `include=type` each time. * **Cache entire query responses** for endpoints that don’t change often (e.g. historical stats, standings). * Use a **cache-aside** or **lazy caching** model: on a cache miss, fetch from the API, store it, then respond. * Set sensible TTLs (time-to-live) depending on how often that data really changes. * Invalidate or refresh caches when you know an underlying change occurred (for example, via webhooks or scheduled refreshes). **Example scenario** Imagine your UI shows standings for a season. Rather than: 1. Fetch `/standings?season=2025&include=league,team` every refresh 2. Parse and re-resolve team names each time You could: * On first request, call `/standings?season=2025&include=league,team` * Cache the `league` and `team` lookups locally * For subsequent requests (especially within a short timeframe), call `/standings?season=2025` (no includes) and use your cache to resolve teams and league metadata This approach reduces payload size and speeds up responses. **Trade-offs and caveats** * **Stale cache risk**: If the underlying data changes (e.g. a team name update), your cache may serve obsolete data. Mitigate this by TTL, invalidation logic, or periodic refreshes. * **Cache memory / storage constraints**: Don’t cache everything. Focus on frequently used, relatively stable data. * **Over-caching dynamic endpoints**: Avoid caching endpoints with highly volatile data (live scores, events) unless on very short TTLs. * **Partial includes**: Sometimes it’s useful to include only subfields rather than the full object to reduce payload. **Best practices summary** * Prioritise server-side filters over client-side filtering * Cache entity lookups (teams, types, etc.) aggressively * Cache query results only when data stability permits * Use lazy loading / cache-aside patterns * Choose TTLs appropriate to data volatility * Include invalidation / refresh mechanisms * Monitor cache hit rates and misses to guide tuning ### Master the tools: Request options deep dive These best practices rely on mastering one essential skill: using request options effectively. If you haven't already, dive deep into the **Request Options** documentation to understand: * How to use **includes** to enrich your responses without making multiple API calls * How to **filter data** on the server-side (not client-side) for better performance * How to **select specific fields** to minimize payload size and improve response times * How to **order and sort** results the way your application needs them By combining these request options with the best practices above, caching strategies, rate limit awareness, and efficient data retrieval, you'll build applications that are faster, cheaper, and more scalable. [Master Request Options →](https://docs.sportmonks.com/football/api/request-options) # ✨ Sportmonks AI Docs Documentation for integrating Sportmonks football data with AI tools and LLMs. ### Structure ``` ✨ Sportmonks AI Docs ├── AI Developer Hub ├── Machine Readable Docs ├── Cursor Rules ├── Vibe Coding ├── Example Builds ├── MCP Server (Beta) │ ├── Quick Start │ ├── Prompts │ ├── Resources │ ├── Example Prompts │ ├── Setup │ │ ├── Claude Code │ │ ├── Claude Desktop │ │ └── Cursor │ └── Tools │ ├── Search │ ├── Players, Teams & Leagues │ ├── Squads │ ├── Fixtures │ └── Standings, Seasons & Top Scorers └── LLM Tools ├── ChatGPT ├── Github Copilot └── Windsurf ``` ### GitBook navigation order This is the current sidebar structure: 1. AI Developer Hub 2. Machine Readable Docs 3. Cursor Rules 4. Example Builds 5. **MCP Server (BETA)** * Quick Start * Prompts * Resources * Example Prompts * Setup * Claude Code * Claude Desktop * Cursor * Tools * Search * Players, Teams & Leagues * Squads * Fixtures * Standings, Seasons & Top Scorers 6. **LLM Tools** * ChatGPT * GitHub Copilot * Windsurf # AI Developer Hub Get live football data into any AI workflow - from a conversational assistant in Claude to accurate code generation in Cursor and Copilot. Choose the integration that fits how you work. ### Claude and Cursor - MCP Server *(BETA)* The deepest integration. Install the MCP server and your AI assistant calls the Sportmonks API live during the conversation - no copy-pasting, no manual lookups, no stale data. > The MCP server covers a focused set of football data endpoints. It is designed for exploration and prototyping, not production API usage. * MCP Server overview * Quick start * Setup for Claude Code * Setup for Claude Desktop * Setup for Cursor ### ChatGPT Use the Sportmonks OpenAPI spec to create a Custom GPT with Actions. Anyone can query live football data from ChatGPT without writing a line of code. * ChatGPT Custom GPT setup ### GitHub Copilot Add a workspace instructions file and Copilot writes accurate Sportmonks integration code - correct endpoints, proper auth patterns, right response shapes - from the first suggestion. * GitHub Copilot setup ### Windsurf Cascade supports MCP natively. Install the server and Windsurf has the same live tool access as Claude. * Windsurf setup ### Any other LLM Paste a context block into ChatGPT, Gemini, Mistral, or anything else - and it will understand the Sportmonks API well enough to help you build, without any installation. * Machine-readable docs ### Not sure where to start? | I want to... | Start here | | -------------------------------------------------- | ------------------------------ | | Query live data by asking questions | MCP Server | | Build Sportmonks integrations faster in my editor | Cursor Rules or GitHub Copilot | | Give non-technical users a football data assistant | ChatGPT Custom GPT | | Explore what's possible in a weekend | Example Builds | # Machine Readable Docs Copy one of the context blocks below and paste it into any AI tool. It gives the AI enough knowledge of the Sportmonks API to help you build - no installation, no setup. Works with Claude, ChatGPT, Gemini, Mistral, Copilot, Cursor, and any other LLM. ### Which block should I use? | Block | Size | Best for | | ------------ | --------------- | ----------------------------------------------------------------------------------- | | Minimal | \~400 tokens | Quick questions, one-off lookups, tight context budgets | | Full | \~2,000 tokens | Building something real - endpoints, includes, filters, and common IDs all included | | OpenAPI spec | \~22,000 tokens | Tool configuration, code generation, or Custom GPT Actions | ### Minimal context ``` Sportmonks Football API v3 Base URL: https://api.sportmonks.com/v3/football Auth: ?api_token=YOUR_TOKEN (query parameter on every request) Key endpoints: GET /players/search/{query} GET /teams/search/{query} GET /leagues/search/{query} GET /fixtures/{id} GET /fixtures/date/{date} GET /livescores/inplay GET /squads/teams/{team_id} GET /standings/live/leagues/{league_id} GET /topscorers/seasons/{season_id} Includes: semicolon-separated (e.g. include=participants;scores;league;state) Filters: key:value syntax (e.g. filters=fixtureLeagues:8) Pagination: ?page=1&per_page=25 Docs: https://docs.sportmonks.com/football ``` ### Full context ``` Sportmonks Football API v3 Base URL: https://api.sportmonks.com/v3/football Core API: https://api.sportmonks.com/v3/core Auth: ?api_token=YOUR_TOKEN on every request --- SEARCH --- GET /players/search/{query} GET /teams/search/{query} GET /leagues/search/{query} --- PLAYERS & TEAMS --- GET /players/{id} GET /teams/{id} GET /leagues/{id} --- SQUADS --- GET /squads/teams/{team_id} GET /squads/seasons/{season_id}/teams/{team_id} --- FIXTURES --- GET /fixtures/{id} GET /fixtures/date/{date} GET /fixtures/between/{start}/{end} GET /fixtures/between/{start}/{end}/{team_id} GET /fixtures/head-to-head/{team1_id}/{team2_id} GET /livescores/inplay GET /livescores --- STANDINGS --- GET /standings/seasons/{season_id} GET /standings/live/leagues/{league_id} GET /standings/rounds/{round_id} --- TOPSCORERS --- GET /topscorers/seasons/{season_id} Common type IDs: goals=208, assists=209, yellow cards=84 --- INCLUDES --- Pass as semicolon-separated string: participants - the two teams scores - current and final scoreline state - match state (NS/LIVE/HT/FT/AET/PEN) league - league name and ID round - gameweek/matchday events - goals, cards, substitutions lineups - starting XI and bench statistics - team stats (shots, possession, corners, etc.) periods - first half, second half breakdown venue - stadium info player - full player object (nest inside squad/lineup) position - player position detailedPosition - more granular position --- FILTERS --- Pass as key:value syntax: fixtureLeagues:{league_id} - filter fixtures by league fixtureStates:{state_id,state_id} - filter by match state (2=1H, 22=2H) fixturestatisticTypes:{type_ids} - filter stat types eventTypes:{type_ids} - filter event types seasonTopscorerTypes:{type_id} - filter topscorer type --- PAGINATION --- ?page=1&per_page=25&order=asc --- COMMON IDs --- Premier League: league_id=8 La Liga: league_id=564 Bundesliga: league_id=82 Serie A: league_id=384 Ligue 1: league_id=301 Champions League: league_id=2 World Cup 2026: league_id=732, season_id=26618 Docs: https://docs.sportmonks.com/football ``` ### OpenAPI specification The full OpenAPI spec for the Sportmonks Football API v3. Import it into your AI tool, code editor, or use it to configure a Custom GPT Action. [Download OpenAPI spec](https://static.sportmonks.com/openapi_spec.json) > At \~22,000 tokens this is large. Use the minimal or full context blocks above for most tasks - reserve the spec for tool configuration or code generation. ### llms.txt Sportmonks publishes a machine-readable documentation index following the [llms.txt standard](https://llmstxt.org): ``` https://docs.sportmonks.com/llms.txt ``` AI tools and crawlers can fetch this to get a structured overview of all Sportmonks APIs - Football, Motorsport, Odds, Core, and Widgets. Paste the URL into any AI tool to give it a broad orientation before diving into a specific API. # Cursor Rules A pre-configured rules file for Sportmonks API development in Cursor. Drop it into your project and Cursor will write accurate integration code without needing the MCP server installed. ### Setup Create a file at `.cursor/rules/sportmonks.mdc` in your project root and paste the content below. ``` --- description: Sportmonks Football API v3 integration rules globs: ["**/*.ts", "**/*.js", "**/*.py", "**/*.go"] --- # Sportmonks Football API v3 ## Base URLs - Football API: https://api.sportmonks.com/v3/football - Core API: https://api.sportmonks.com/v3/core ## Authentication Always pass the API token as a query parameter: ?api_token=process.env.SPORTMONKS_API_TOKEN Never hardcode the token. Always read from environment variables. ## Includes Pass as semicolon-separated string in the `include` query parameter: ?include=participants;scores;state;league Common includes: - participants: the two teams in a fixture - scores: current and final scoreline - state: match state (NS, LIVE, HT, FT, AET, PEN) - league: league name and ID - round: gameweek/matchday - events: goals, cards, substitutions - lineups: starting XI and bench - statistics: team stats - periods: half-time/full-time breakdown - player: full player object (nest inside squad or lineup includes) - position: player position ## Filters Pass as key:value in the `filters` query parameter: ?filters=fixtureLeagues:8 Common filters: - fixtureLeagues:{id} - filter fixtures by league - fixtureStates:{id1,id2} - filter by match state - seasonTopscorerTypes:{id} - filter topscorer category ## Pagination Use `page` and `per_page` query parameters. Default per_page is 25. ## Key endpoints ### Search GET /players/search/{query} GET /teams/search/{query} GET /leagues/search/{query} ### Players & Teams GET /players/{id}?include=position;nationality;teams GET /teams/{id}?include=venue;country GET /leagues/{id}?include=country;seasons ### Squads GET /squads/teams/{team_id}?include=player;position;detailedPosition GET /squads/seasons/{season_id}/teams/{team_id}?include=player;position ### Fixtures GET /fixtures/{id}?include=participants;scores;state;league GET /fixtures/date/{date}?include=participants;scores;state GET /fixtures/between/{start_date}/{end_date} GET /fixtures/between/{start_date}/{end_date}/{team_id} GET /fixtures/head-to-head/{team1_id}/{team2_id} GET /livescores/inplay?include=participants;scores;state ### Standings GET /standings/seasons/{season_id}?include=participant;details GET /standings/live/leagues/{league_id}?include=participant;details ### Topscorers GET /topscorers/seasons/{season_id}?include=player;participant&filters=seasonTopscorerTypes:208 Type IDs: goals=208, assists=209, yellow cards=84 ### Odds GET /odds/pre-match/fixtures/{fixture_id}?include=bookmaker;market GET /odds/inplay/fixtures/{fixture_id}?include=bookmaker;market ## Response shape All responses wrap data in a `data` key: { "data": { ... } } for single items { "data": [...], "pagination": { ... } } for lists Always access response.data, not the response directly. ## Common league IDs Premier League: 8 La Liga: 564 Bundesliga: 82 Serie A: 384 Ligue 1: 301 Champions League: 2 World Cup 2026: league_id=732, season_id=26618 ## Error handling - 401/403: invalid token or plan restriction - 404: resource not found - 429: rate limit exceeded - back off and retry - Always handle these explicitly, never swallow errors silently ## Best practices - Use the search endpoints to resolve names to IDs before fetching detail - Request only the includes you need - each include adds to response size - Cache league, season, and team IDs - they don't change - For live apps, poll /livescores/inplay or /fixtures/date/{today} on a short interval ``` ### What this does Once the file is in place, Cursor will apply these rules automatically when you're working in TypeScript, JavaScript, Python, or Go files. You'll get: * Correct endpoint paths without looking them up * Proper include and filter syntax * Right response shapes for destructuring * Environment variable patterns instead of hardcoded tokens * Accurate common IDs for top leagues ### Global rules (optional) To apply the rules across all projects instead of just one, add them to your global Cursor rules file at `~/.cursor/rules/sportmonks.mdc`. # Vibe Coding Describe what you want to build. Let the AI write the code. Ship it. This page gives you everything you need to build with the Sportmonks Football API using any AI coding tool - the right context, and ready-to-run prompts for common football data builds. ### Give your AI the right context For the AI to write accurate Sportmonks integration code, it needs to know the API. Pick one of the options below and give it to your AI tool before you start building. #### llms.txt - full documentation index Sportmonks publishes a machine-readable index of all its APIs at: ``` https://docs.sportmonks.com/llms.txt ``` Paste this URL into Claude, ChatGPT, or Cursor and ask it to fetch the content. This gives the AI a broad picture of every Sportmonks API before you start. #### Context block - Football API quick reference For faster setup, paste this directly into your session: ``` Sportmonks Football API v3 Base URL: https://api.sportmonks.com/v3/football Auth: ?api_token=YOUR_TOKEN (query parameter on every request) Key endpoints: GET /players/search/{query} GET /teams/search/{query} GET /leagues/search/{query} GET /fixtures/{id} GET /fixtures/date/{date} GET /livescores/inplay GET /squads/teams/{team_id} GET /standings/live/leagues/{league_id} GET /topscorers/seasons/{season_id} Includes: semicolon-separated (e.g. include=participants;scores;league;state) Filters: key:value syntax (e.g. filters=fixtureLeagues:8) Pagination: ?page=1&per_page=25 Docs: https://docs.sportmonks.com/football ``` For a more complete reference with all endpoints, includes, filters, and common IDs, see the full context block. #### Cursor Rules or Copilot instructions If you use Cursor or GitHub Copilot, you can make the API knowledge persistent across your whole project - no need to paste context every session. * Cursor Rules * GitHub Copilot instructions ### Build prompts Each prompt below is ready to paste into your AI tool. They're written to produce working code against the real API - not mock data. > **Note:** These prompts guide the AI to write code that calls the Sportmonks API directly from your application. This is different from the MCP server, which is a companion tool for exploring data conversationally - not for generating application code. #### Live score dashboard A real-time dashboard that polls for in-play matches and updates every 30 seconds. ``` I'm building with the Sportmonks Football API v3. Base URL: https://api.sportmonks.com/v3/football Auth: api_token query parameter, read from SPORTMONKS_API_TOKEN env var. Build a live score dashboard: - Fetch in-play matches from GET /livescores/inplay?include=participants;scores;state;periods - Display each match as a card: home team, away team, current score, match state (1H/HT/2H), elapsed minutes - Poll every 30 seconds and update without a full page reload - Show a "No live matches right now" empty state when the feed is empty Use React and Tailwind CSS. First, fetch a real sample response from the endpoint and print the raw JSON so we can confirm the data shape before writing any UI. ``` #### Pre-match briefing card Given a fixture ID, generate a briefing with team details, head-to-head history, and current league positions. ``` I'm building with the Sportmonks Football API v3. Base URL: https://api.sportmonks.com/v3/football Auth: api_token query parameter, read from SPORTMONKS_API_TOKEN env var. Build a pre-match briefing generator: 1. Accept a fixture ID as input 2. Fetch the fixture: GET /fixtures/{id}?include=participants;league;state 3. Extract the two team IDs from participants, then fetch: GET /fixtures/head-to-head/{team1_id}/{team2_id}?per_page=5&order=desc&include=participants;scores 4. Fetch current standings: GET /standings/live/leagues/{league_id}?include=participant;details Render a briefing card showing: - Match title, kick-off time, competition name - Last 5 H2H results as a compact table (date, result, score) - Current league position for each team (position, played, points) Use Next.js with Tailwind. Accept the fixture ID as a URL param (/briefing?fixture=123456). Start by printing the raw API responses for fixture 19135697 before writing any UI. ``` #### Squad viewer Search for any team by name and browse their current squad grouped by position. ``` I'm building with the Sportmonks Football API v3. Base URL: https://api.sportmonks.com/v3/football Auth: api_token query parameter, read from SPORTMONKS_API_TOKEN env var. Build a squad viewer: 1. A search input that calls GET /teams/search/{query} and shows results as a clickable list 2. On team select, fetch: GET /squads/teams/{team_id}?include=player;position;detailedPosition 3. Display the squad grouped by position (Goalkeepers, Defenders, Midfielders, Attackers), each player showing name, jersey number, and detailed position Use React and Tailwind. First fetch team_id 85 (Arsenal) squad and print the raw JSON to confirm the response shape before building the UI. ``` #### Top scorers leaderboard A season leaderboard for goals, assists, or yellow cards with a toggle to switch between them. ``` I'm building with the Sportmonks Football API v3. Base URL: https://api.sportmonks.com/v3/football Auth: api_token query parameter, read from SPORTMONKS_API_TOKEN env var. Build a top scorers leaderboard: 1. On load, fetch the Premier League's current season: GET /leagues/8?include=currentseason 2. Fetch the top 25 goal scorers: GET /topscorers/seasons/{season_id}?include=player;participant;type&filters=seasonTopscorerTypes:208&per_page=25 3. Show a ranked table: position, player name, team, count 4. Add a toggle between goals (type 208), assists (type 209), and yellow cards (type 84) - re-fetch on switch Use React and Tailwind. Show a skeleton loader while fetching. Start by printing the league and topscorers responses before writing any UI. ``` #### Discord match alert bot A Node.js script that posts to Discord when a match kicks off or ends. ``` I'm building with the Sportmonks Football API v3. Base URL: https://api.sportmonks.com/v3/football Auth: api_token query parameter, read from SPORTMONKS_API_TOKEN env var. Build a Discord alert bot in Node.js: 1. Poll GET /livescores/inplay?include=participants;scores;state every 60 seconds 2. Track which fixture IDs have already been announced in memory 3. New match in the feed: post "🟢 KICK OFF: {home} vs {away}" to Discord 4. Match disappears from feed: post "⏹ FULL TIME: {home} {score} {away}" 5. Read SPORTMONKS_API_TOKEN and DISCORD_WEBHOOK_URL from environment variables Single index.js file, no framework. Use node-fetch for HTTP and the Discord webhook API for posting. ``` ### Tips * **Fetch real data first.** Every prompt above asks the AI to print the raw API response before building UI. This prevents the AI from guessing the wrong response shape. * **Search before you hardcode.** Ask the AI to use the search endpoints to resolve names to IDs rather than hardcoding them. * **Iterate in plain English.** Once there's a working base, describe changes conversationally - "group players by position", "add a loading skeleton", "make the cards darker". * **Use the full context block for complex builds.** For anything beyond a single endpoint, paste the full context so the AI knows the complete include and filter syntax upfront. # Example Builds Concrete things you can build with AI and Sportmonks data. Each of these is achievable in an afternoon using any AI coding tool with the MCP server or a context block. ### Live score dashboard A real-time dashboard that polls for in-play matches and displays scores, match state, and elapsed minutes. **What you need:** * `GET /livescores/inplay?include=participants;scores;state;periods` * A polling loop (every 30-60 seconds) * A simple UI framework (React, Vue, or plain HTML) **Ask your AI:** > *Build a live score dashboard that polls the Sportmonks inplay livescores endpoint every 30 seconds and renders a card for each match showing home team, away team, score, and current minute. Use React and Tailwind.* ### Pre-match briefing generator Paste a fixture ID and get a formatted pre-match briefing with team info, recent form, and head-to-head history. **What you need:** * `GET /fixtures/{id}?include=participants` * `GET /fixtures/head-to-head/{team1}/{team2}?per_page=5&order=desc` * `GET /standings/live/leagues/{league_id}?include=participant;details` **Ask your AI:** > *Build a pre-match briefing generator. Given a fixture ID, fetch the two teams, their last 5 head-to-head results, and their current league positions. Format everything as a clean markdown report.* ### Odds comparison table A side-by-side odds comparison across bookmakers for a given fixture and market. **What you need:** * `GET /odds/pre-match/fixtures/{fixture_id}?include=bookmaker;market` * Filter by market (e.g. 1X2) and sort by bookmaker **Ask your AI:** > *Build an odds comparison function that takes a fixture ID and returns a table showing the home win, draw, and away win odds from every available bookmaker, sorted by best home win odds.* ### Transfer tracker A feed of the latest transfer activity across subscribed leagues, updated on demand. **What you need:** * `GET /transfers/latest?include=player;fromTeam;toTeam` * Optional date range filtering **Ask your AI:** > *Build a transfer tracker that fetches the 20 most recent transfers and displays them as a feed with player name, from club, to club, and transfer date. Add a filter for specific leagues.* ### League season explorer A tool that lets users pick a league, browse its historical seasons, and jump to standings or topscorers for any of them. **What you need:** * `GET /leagues/search/{query}` * `GET /leagues/{id}?include=seasons` * `GET /standings/seasons/{season_id}?include=participant;details` * `GET /topscorers/seasons/{season_id}?filters=seasonTopscorerTypes:208` **Ask your AI:** > *Build a league explorer. The user types a league name, picks from the search results, then sees a list of all historical seasons. Clicking a season shows the final standings table and top 10 scorers.* ### Tips for building with AI * **Start with search** - ask the AI to use the search endpoint to find IDs before writing the rest of the code. It avoids hardcoded IDs that break. * **Use the context block** - paste the full context at the start of your session so the AI knows the endpoint shapes upfront. * **Ask for real data first** - before writing UI code, ask the AI to fetch a live sample response and print it. It avoids building against the wrong shape. * **Install the MCP server** - if you're in Claude or Cursor, the AI can fetch real data mid-conversation to test its own code as it writes it. # MCP Server (Beta) > **This server is currently in beta.** Functionality may change and some edge cases may not be fully handled. We welcome your feedback - see the Feedback section below. The Sportmonks Football MCP server connects AI tools like Claude and Cursor directly to the Sportmonks Football API v3. > **Companion tool, not a production API client.** The MCP server is designed for exploration and experimentation - letting you query football data conversationally without writing integration code. It covers a focused subset of the full API and is not intended as a replacement for direct API integration in production applications. The server exposes **11 focused tools** covering the most common football data needs. ### What is MCP? MCP (Model Context Protocol) is an open standard that lets AI assistants call external APIs as tools. When you install an MCP server, the AI can discover its available tools and call them on your behalf during a conversation - fetching real data, not hallucinating it. ### What you can do * Ask "who are the top scorers in the Premier League this season?" and get live data back * Say "give me a match preview for the Arsenal vs Chelsea fixture" and get a full briefing with head-to-head history * Ask "show me the current La Liga standings" without looking up a single ID * Explore API responses interactively before building an integration ### Tools at a glance | Tool | What it does | | ---------------------- | --------------------------------------------------------- | | `search` | Find players, teams, or leagues by name | | `get_player` | Full player profile by ID | | `get_team` | Team profile by ID | | `get_league` | League details by ID | | `get_squad` | Current or historical squad for a team | | `get_matches` | Upcoming, live, or historic fixtures for a team or league | | `get_match_preview` | Fixture info plus last 5 head-to-head results | | `get_fixture_details` | Detailed match data - lineups, events, statistics | | `get_standings` | Live league table | | `get_historic_seasons` | All seasons for a league, newest first | | `get_topscorers` | Goals, assists, or cards leaderboard for a season |

### Next steps * Quick Start - get up and running in minutes * Setup - install the MCP server for Claude Code, Claude Desktop, or Cursor * Example Prompts - see what you can ask ### Feedback The MCP server is in active development. If you run into issues, unexpected results, or have suggestions for new tools or improvements, send feedback to ****. Please include: * The tool you called and the arguments you passed * What you expected vs. what you got * Your AI client (Claude Desktop, Claude Code, Cursor, etc.) # Quick Start ### 1. Get your API token Sign in at [my.sportmonks.com](https://my.sportmonks.com/subscriptions) and copy your API token. ### 2. Install the server No cloning or building required. The server is published on npm and runs directly via `npx`. ### 3. Register with your AI tool **Claude Code** ```bash claude mcp add sportmonks-football \ --env SPORTMONKS_API_TOKEN="your_token" \ -- npx sportmonks-football-mcp-server ``` **Claude Desktop** - add to your config file: ```json { "mcpServers": { "sportmonks-football": { "command": "npx", "args": ["sportmonks-football-mcp-server"], "env": { "SPORTMONKS_API_TOKEN": "your_token" } } } } ``` Config file locations: * **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` * **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

### 4. Try it ``` Search for "Arsenal" and show me their upcoming fixtures ``` ``` Give me the current Premier League standings ``` ``` Who are the top 10 scorers in La Liga this season? ``` Full setup instructions for each platform: Claude Code · Claude Desktop · Cursor > Not using Claude? The MCP server also works with Cursor and Windsurf. For ChatGPT and GitHub Copilot, see the AI Tools section for setup options that don't require MCP. # Prompts Prompts are pre-built briefings that orchestrate multiple API calls server-side and return structured, presentation-ready content in a single command. They appear as native actions in supported clients like Claude Desktop. ### Available prompts | Prompt | Description | | ----------------- | -------------------------------------------------------------- | | `match_preview` | Pre-match briefing with fixture details and last 5 H2H results | | `team_overview` | Team profile, upcoming fixtures, and current league standing | | `league_overview` | Full standings table and upcoming fixtures for a league | ### match\_preview Generates a concise pre-match briefing for an upcoming fixture. Fetches the fixture details and the last 5 head-to-head results between the two teams. > Only works for fixtures that have **not yet started**. **Arguments** | Argument | Required | Description | | ------------ | -------- | ------------------------------------------- | | `fixture_id` | Yes | Sportmonks fixture ID for an upcoming match | **Output includes:** match details, kick-off time, and a head-to-head table showing scores and results from the last 5 meetings. ### team\_overview Generates a team briefing pulling together entity details, upcoming fixtures for the next 14 days, and the team's current position in their league table. **Arguments** | Argument | Required | Description | | --------- | -------- | ------------------ | | `team_id` | Yes | Sportmonks team ID | **Output includes:** team name, country, venue, upcoming fixture list, and current league standing (position, played, won, drawn, lost, GD, points). ### league\_overview Generates a full league briefing with the complete standings table and all upcoming fixtures for the next 14 days. **Arguments** | Argument | Required | Description | | ----------- | -------- | -------------------- | | `league_id` | Yes | Sportmonks league ID | **Output includes:** league name, country, full standings table, and upcoming fixture list. ### How to use prompts Prompts are part of the MCP protocol. When invoked, the server fetches live data from Sportmonks, formats it into a structured briefing, and returns it as a user message for the AI to respond to. #### Claude Code and Cursor Reference the prompt by name in your message: ``` Run the match_preview prompt for fixture ID 19135697 ``` ``` Use the team_overview prompt for team ID 85 ``` ``` Generate a league_overview for league ID 8 ``` #### Claude Desktop Claude Desktop surfaces MCP prompts in the UI - the exact location depends on your version. If you don't see a dedicated prompt picker, you can invoke them the same way as Claude Code: just ask by name with the required argument. # Resources The MCP server exposes two resources that MCP clients can read directly - no tool call required. | URI | What it contains | | ---------------------------- | --------------------------------------------------------------------------- | | `sportmonks://documentation` | Server overview, tool list, auth setup, and usage notes | | `sportmonks://openapi` | Full OpenAPI specification for the Sportmonks Football API v3, fetched live | ### sportmonks\://documentation A plain-text overview of the server covering all available tools, authentication setup, behaviour notes (result limits, timeframes, search caps), and links to the official Sportmonks documentation. **Best used for:** giving an AI assistant a quick orientation about the server at the start of a session. ### sportmonks\://openapi The full OpenAPI specification for the Sportmonks Football API v3, fetched live when read. Gives an AI assistant complete visibility into every endpoint, parameter, and response shape. **Best used for:** building API client code, writing TypeScript types from real schemas, or generating a Custom GPT Action. ### How to read a resource **Claude Code** Ask the AI directly by URI: ``` Read the sportmonks://documentation resource ``` ``` Read sportmonks://openapi and use it to write a TypeScript type for the fixtures response ``` **Claude Desktop** Resources may appear in the attachment or context menu depending on your client version. If not visible in the UI, ask for them by URI the same way as Claude Code above. # Example Prompts Things you can ask once the MCP server is connected. Copy any of these directly into Claude, Cursor, or Windsurf. > Want broader build ideas using all AI tools? See Example Builds. ### Finding things *Search for "Barcelona" - is it a team, a league, or both?* *Find the player ID for Erling Haaland* *Search for leagues named "Premier League" - how many are there?* ### Teams and players *Get the profile for Manchester City* *Show me the current squad for Liverpool* *Who was in Arsenal's squad during the 2021/22 season?* *Get the profile for Vinicius Jr - which club is he at?*

### Fixtures *Show me Real Madrid's upcoming fixtures for the next two weeks* *What were Chelsea's results over the last 30 days?* *Are there any live matches right now?* *Get the full details for fixture 123456 including lineups and events* ### Standings and seasons *Show me the current Premier League standings* *What seasons has the Champions League had? Give me the most recent ones first* *Who are the top 10 goal scorers in Serie A this season?* *Show me the top 5 assist providers and top 5 yellow card recipients in the Bundesliga* ### Pre-built briefings *Give me a pre-match briefing for the upcoming El Clasico - use the match\_preview prompt* *Run the team\_overview prompt for Manchester United* *Generate a league\_overview for the Premier League* ### Building with the API *Fetch a sample fixture response using get\_fixture\_details, then write me a TypeScript interface for the response shape* *Use get\_standings to get the current La Liga table and format it as a markdown table* *Build a function that takes a team name, searches for it, then fetches its next 5 fixtures* # Setup Step-by-step install guides for the Sportmonks MCP server on each supported platform. | Platform | Guide | | -------------- | -------------------------------------- | | Claude Code | CLI-based install via `claude mcp add` | | Claude Desktop | Config file install | | Cursor | Global or project-scoped MCP config | ### Before you start You'll need: * [Node.js 18+](https://nodejs.org) * A Sportmonks API token - get one at [my.sportmonks.com](https://my.sportmonks.com/subscriptions) * The AI tool you want to connect already installed The server is published on npm as `sportmonks-football-mcp-server`. There is no cloning or building required - your AI tool will download and run it automatically via `npx`. Then follow the guide for your platform above. # Claude Code ### Prerequisites * [Node.js 18+](https://nodejs.org) * A Sportmonks API token from [my.sportmonks.com](https://my.sportmonks.com/subscriptions) * [Claude Code](https://claude.ai/code) installed ### Install **1. Register the MCP server** ```bash claude mcp add sportmonks-football \ --env SPORTMONKS_API_TOKEN="your_token" \ -- npx -y sportmonks-football-mcp-server ``` **2. Verify** ```bash claude mcp list ``` You should see `sportmonks-football` with status `Connected`. ### Environment variables | Variable | Required | Description | | ----------------------- | -------- | --------------------------------------------------------------------------------------------- | | `SPORTMONKS_API_TOKEN` | Yes | Your Sportmonks API token | | `SPORTMONKS_LOG_FILE` | No | Path for the local tool-call log. Set to `off` to disable. Defaults to your OS temp directory | | `SPORTMONKS_DEBUG_URLS` | No | Set to `1` or `true` to log outbound API URLs to stderr (token redacted). Off by default | ### Test it Open Claude Code and ask: ``` Search for "Liverpool" and show me their current squad ``` ### Updating The server runs via `npx`, so you always get the latest published version automatically. No manual update steps needed. # Claude Desktop ### Prerequisites * [Node.js 18+](https://nodejs.org) * A Sportmonks API token from [my.sportmonks.com](https://my.sportmonks.com/subscriptions) * [Claude Desktop](https://claude.ai/download) installed ### Install **1. Edit your Claude Desktop config** Open the config file for your operating system: * **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` * **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` Add the following: ```json { "mcpServers": { "sportmonks-football": { "command": "npx", "args": ["-y", "sportmonks-football-mcp-server"], "env": { "SPORTMONKS_API_TOKEN": "your_token" } } } } ``` Optional environment variables can be added to the `env` block: | Variable | Description | | ----------------------- | --------------------------------------------------------------------------------------------- | | `SPORTMONKS_LOG_FILE` | Path for the local tool-call log. Set to `off` to disable. Defaults to your OS temp directory | | `SPORTMONKS_DEBUG_URLS` | Set to `1` or `true` to log outbound API URLs to stderr (token redacted). Off by default | **2. Restart Claude Desktop** The Sportmonks tools will be available in your next conversation.

### Test it Start a new conversation and ask: ``` Show me the current Premier League standings ``` ### Updating The server runs via `npx`, so you always get the latest published version automatically. No manual update steps needed. # Cursor ### Prerequisites * [Node.js 18+](https://nodejs.org) * A Sportmonks API token from [my.sportmonks.com](https://my.sportmonks.com/subscriptions) * [Cursor](https://cursor.sh) installed ### Install **1. Add to Cursor** Open Cursor → **Settings** → **Cursor Settings** → **MCP** → **Add new global MCP server** Or edit `~/.cursor/mcp.json` directly: ```json { "mcpServers": { "sportmonks-football": { "command": "npx", "args": ["-y", "sportmonks-football-mcp-server"], "env": { "SPORTMONKS_API_TOKEN": "your_token" } } } } ``` Optional environment variables can be added to the `env` block: | Variable | Description | | ----------------------- | --------------------------------------------------------------------------------------------- | | `SPORTMONKS_LOG_FILE` | Path for the local tool-call log. Set to `off` to disable. Defaults to your OS temp directory | | `SPORTMONKS_DEBUG_URLS` | Set to `1` or `true` to log outbound API URLs to stderr (token redacted). Off by default | **2. Restart Cursor** The Sportmonks tools will appear in the Agent panel. ### Test it Open the Cursor Agent and ask: ``` Give me the la liga table using the sportmonks mcp ```

### Project-scoped config To scope the server to one project only, create `.cursor/mcp.json` in your project root with the same config above instead of editing the global file. ### Updating The server runs via `npx`, so you always get the latest published version automatically. No manual update steps needed. # Tools The Sportmonks MCP server exposes 11 tools covering the most common football data needs. Every tool is available in Claude, Cursor, and Windsurf once the server is installed. ### Tool reference | Page | Tools covered | | ------------------------------- | --------------------------------------------------------- | | Search | `search` | | Players, Teams & Leagues | `get_player`, `get_team`, `get_league` | | Squads | `get_squad` | | Fixtures | `get_matches`, `get_match_preview`, `get_fixture_details` | | Standings, Seasons & Topscorers | `get_standings`, `get_historic_seasons`, `get_topscorers` | ### How to use tools Tools are called automatically by the AI during a conversation. You don't invoke them directly - just ask a question in natural language and the AI picks the right tool. ``` Show me the current Premier League standings ``` The AI calls `get_standings` internally and returns the formatted table. ### Typical workflow Most tasks follow this pattern: 1. **Search** - use `search` to find the ID of a team, player, or league by name 2. **Fetch** - use the relevant tool with that ID to get the data you need 3. **Combine** - chain tools together for richer results (e.g. get a league ID, then fetch its standings and topscorers) # Search The `search` tool is usually the right starting point. Use it to find the ID of a player, team, or league before calling other tools. ### Tool | Tool | Description | | -------- | ----------------------------------------------------------- | | `search` | Search players, teams, leagues, or all entity types by name | ### Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------------------------------------------------------ | | `query` | string | Yes | Name or partial name to search for | | `type` | string | No | Entity type to search: `player`, `team`, `league`, or `all`. Defaults to `all` | ### Response Returns up to 25 results sorted alphabetically. Each result includes: ```json { "id": 123, "entity_type": "team", "name": "Arsenal", "country": "England" } ``` The `country` field helps disambiguate results where many entities share the same name (e.g. multiple leagues named "Super League" across different countries). ### Example prompts * *Search for "Arsenal"* * *Search for players named "Silva"* * *Find the league ID for the Premier League* * *Search for "Haaland" - player only* # Players, Teams & Leagues Fetch full profiles for players, teams, and leagues by their Sportmonks ID. Use the `search` tool first if you don't know the ID. ### Tools | Tool | Description | | ------------ | ------------------------------------------- | | `get_player` | Full player profile by Sportmonks player ID | | `get_team` | Team profile by Sportmonks team ID | | `get_league` | League details by Sportmonks league ID | ### get\_player **Parameters** | Parameter | Type | Required | Description | | --------- | ------- | -------- | -------------------- | | `id` | integer | Yes | Sportmonks player ID | **Returns:** name, position, nationality, date of birth, current team (resolved via a two-step lookup). ### get\_team **Parameters** | Parameter | Type | Required | Description | | --------- | ------- | -------- | ------------------ | | `id` | integer | Yes | Sportmonks team ID | **Returns:** name, country, venue. ### get\_league **Parameters** | Parameter | Type | Required | Description | | --------- | ------- | -------- | -------------------- | | `id` | integer | Yes | Sportmonks league ID | **Returns:** name, country, current\_season\_id, current\_season\_name. ### Example prompts * *Get the profile for player ID 14322* * *What country is team 85 from?* * *Get the details for league 8 - what competition is it?* * *Search for "Mbappe" then get his full player profile* # Squads Retrieve the current or a historical squad for any team. ### Tool | Tool | Description | | ----------- | ------------------------------------------------------------------- | | `get_squad` | Squad for a team, optionally scoped to a specific historical season | ### Parameters | Parameter | Type | Required | Description | | ----------- | ------- | -------- | ------------------------------------------------ | | `team_id` | integer | Yes | Sportmonks team ID | | `season_id` | integer | No | Sportmonks season ID. Omit for the current squad | ### Response Returns a list of squad members, each with: ```json { "player_id": 123, "name": "Bukayo Saka", "position": "Attacker", "position_id": 27, "detailed_position": "Right Winger", "detailed_position_id": 153, "jersey_number": 7 } ``` ### Example prompts * *Get the current squad for Manchester City* * *Show me Arsenal's squad - use team ID 42* * *Who was in Liverpool's squad during the 2019/20 season?* * *Search for "Barcelona" to get the team ID, then fetch their current squad* # Fixtures Get upcoming, live, or historic matches for a team or league, preview an upcoming fixture with head-to-head history, or fetch full match details including lineups, events, and statistics. ### Tools | Tool | Description | | --------------------- | ----------------------------------------------------------------- | | `get_matches` | Upcoming, live, or historic fixtures for a team or league | | `get_match_preview` | Fixture info plus the last 5 head-to-head results | | `get_fixture_details` | Detailed match data with optional lineups, events, and statistics | ### get\_matches **Parameters** | Parameter | Type | Required | Description | | ----------- | ------- | -------- | ------------------------------------------- | | `id` | integer | Yes | Sportmonks team ID or league ID | | `type` | string | Yes | `team` or `league` | | `timeframe` | string | No | `upcoming` (default), `live`, or `historic` | **Limits:** * `upcoming` - next 14 days, max 20 fixtures * `historic` - last 30 days, max 20 fixtures * `live` - max 20 fixtures ### get\_match\_preview Returns a fixture summary plus the last 5 head-to-head matches between the two teams. > Only works for fixtures that have **not yet started**. Use `get_matches` with `timeframe: upcoming` to find a valid fixture ID. **Parameters** | Parameter | Type | Required | Description | | --------- | ------- | -------- | --------------------- | | `id` | integer | Yes | Sportmonks fixture ID | ### get\_fixture\_details Returns base fixture data plus any optional expansions you request. **Parameters** | Parameter | Type | Required | Description | | ------------ | ------- | -------- | ----------------------------------------- | | `fixture_id` | integer | Yes | Sportmonks fixture ID | | `includes` | array | No | Any of: `lineups`, `events`, `statistics` | **Base response** includes both teams, scoreline, state, and league. **Optional expansions:** * `lineups` - starting XI and substitutes. Each player includes name, position (resolved label), detailed position, jersey number, and lineup type (starter/substitute) * `events` - goals, cards, and substitutions in chronological order * `statistics` - team stats (shots, possession, corners, etc.) keyed by type name ### Example prompts * *Show me Arsenal's upcoming fixtures for the next two weeks* * *What were Liverpool's results over the last 30 days?* * *Are there any live matches right now?* * *Give me a preview for fixture 19135697 - include the H2H record* * *Get the full details for fixture 19135697 including lineups and statistics* # Standings, Seasons & Top Scorers Get live league tables, browse historical seasons for any league, and fetch topscorer leaderboards. ### Tools | Tool | Description | | ---------------------- | ------------------------------------------------- | | `get_standings` | Live league table for a league ID | | `get_historic_seasons` | All seasons for a league, sorted newest first | | `get_topscorers` | Goals, assists, or cards leaderboard for a season | ### get\_standings Returns standings for a league. The tool first attempts to fetch live standings (which reflect the current matchday in real time). If live standings are unavailable - for example during cup knockout phases, between matchdays, or in the off-season - it falls back to the most recent season standings automatically. **Parameters** | Parameter | Type | Required | Description | | --------- | ------- | -------- | -------------------- | | `id` | integer | Yes | Sportmonks league ID | **Each row returns:** position, team name and ID, played, won, drawn, lost, goal difference, points. ### get\_historic\_seasons Returns all seasons for a league sorted with the most recent first. Useful for finding a `season_id` to pass to `get_topscorers` or `get_squad`. **Parameters** | Parameter | Type | Required | Description | | ----------- | ------- | -------- | -------------------- | | `league_id` | integer | Yes | Sportmonks league ID | ### get\_topscorers **Parameters** | Parameter | Type | Required | Description | | ----------- | ------- | -------- | --------------------------------------------------- | | `season_id` | integer | Yes | Sportmonks season ID | | `type` | string | Yes | `goals`, `assists`, or `cards` | | `limit` | integer | No | Number of results to return. Defaults to 10, max 25 | ### Example prompts * *Show me the current Premier League table* * *What seasons has La Liga had? Give me the most recent ones* * *Who are the top 10 scorers in Serie A this season?* * *Show me the top 5 assist providers in the Bundesliga* * *Get the top 25 yellow card recipients in Ligue 1 this season* # LLM Tools Setup guides for using Sportmonks data with every major AI tool and LLM. Pick the one you use. | Tool | Integration type | What you get | | -------------- | --------------------------- | ---------------------------------------------------------- | | ChatGPT | Custom GPT via GPT Actions | A no-code Sportmonks assistant anyone can use from ChatGPT | | GitHub Copilot | Workspace instructions file | Copilot writes accurate Sportmonks code without prompting | | Windsurf | MCP server for Cascade | Live API access inside Windsurf's AI agent | Looking for Claude or Cursor? Those are covered in the MCP Server section - they use the same server. Not sure which option fits you? If you write code, start with the tool you already use daily. If you want a no-code assistant to query live football data, go with ChatGPT. # ChatGPT Use the Sportmonks OpenAPI spec to create a Custom GPT that can query live football data directly from ChatGPT - no code required. ### What you can build A Custom GPT that lets anyone ask questions like: * *Who are the top scorers in the Premier League right now?* * *Show me live scores* * *What fixtures does Real Madrid have this week?* Without writing a single line of integration code. ### Prerequisites * A ChatGPT Plus, Team, or Enterprise account (Custom GPTs require a paid plan) * A Sportmonks API token from [my.sportmonks.com](https://my.sportmonks.com/subscriptions) ### Setup **1. Open the GPT editor** Go to [chat.openai.com](https://chat.openai.com) → your profile → **My GPTs** → **Create a GPT** **2. Configure the GPT** In the **Create** tab, set a name and description. Suggested: * **Name:** Sportmonks Football Assistant * **Description:** Live football data powered by Sportmonks - fixtures, standings, squads, odds, and more. In the **Instructions** field, paste: ``` You are a football data assistant powered by the Sportmonks Football API v3. When users ask about football data, use the available Actions to fetch live data rather than relying on your training knowledge, which may be outdated. Always: - Search for team, player, or league IDs before fetching detail data - Present data in clean, readable formats (tables, lists) - Mention the data source is Sportmonks when relevant Never invent scores, standings, or player stats. If the API returns no data, say so clearly. ``` **3. Add the Action** Go to the **Configure** tab → scroll to **Actions** → **Create new action** * Set the **Authentication** type to `API Key` * Set **Auth Type** to `Query Param` * Set the **Parameter Name** to `api_token` * Enter your Sportmonks API token as the value Import the schema by pasting the OpenAPI spec URL: ``` https://static.sportmonks.com/openapi_spec.json ``` Or download the spec and paste it directly into the schema editor. **4. Save and test** Click **Save**, then open your new GPT and ask: ``` Search for "Arsenal" and show me their upcoming fixtures ``` ### Sharing your GPT Once created, your Custom GPT can be shared with a link or published to the GPT Store. Anyone with the link can use it - they'll query through your API token, so monitor usage from your Sportmonks dashboard. ### Limitations * Custom GPTs can't maintain state between conversations * Complex multi-step queries may require more explicit prompting * Rate limits apply based on your Sportmonks plan # Github Copilot Add a workspace instructions file to your project and Copilot will write accurate Sportmonks integration code - correct endpoints, proper auth patterns, right response shapes - without you needing to explain the API every time. ### How it works GitHub Copilot reads `.github/copilot-instructions.md` in your repository and uses it as persistent context for all Copilot suggestions in that workspace. Add Sportmonks API knowledge there and Copilot will apply it automatically. ### Setup **1. Create the instructions file** In your project root, create `.github/copilot-instructions.md` and paste the following: ```markdown # Sportmonks Football API v3 ## Base URL https://api.sportmonks.com/v3/football ## Authentication Always use the `api_token` query parameter. Read from environment variables: - Node.js: `process.env.SPORTMONKS_API_TOKEN` - Python: `os.environ["SPORTMONKS_API_TOKEN"]` - Go: `os.Getenv("SPORTMONKS_API_TOKEN")` Never hardcode the token. ## Key endpoints - Search players: GET /players/search/{query} - Search teams: GET /teams/search/{query} - Search leagues: GET /leagues/search/{query} - Player profile: GET /players/{id}?include=position;nationality;teams - Team profile: GET /teams/{id}?include=venue;country - Current squad: GET /squads/teams/{team_id}?include=player;position;detailedPosition - Fixtures by date: GET /fixtures/date/{YYYY-MM-DD}?include=participants;scores;state - Fixture detail: GET /fixtures/{id}?include=participants;scores;state;events;lineups;statistics - Head to head: GET /fixtures/head-to-head/{team1_id}/{team2_id}?per_page=5&order=desc - Live scores: GET /livescores/inplay?include=participants;scores;state - Standings: GET /standings/live/leagues/{league_id}?include=participant;details - Topscorers: GET /topscorers/seasons/{season_id}?include=player;participant&filters=seasonTopscorerTypes:208 ## Includes Semicolon-separated string: ?include=participants;scores;state;league ## Filters Key:value syntax: ?filters=fixtureLeagues:8 ## Response shape All responses: { "data": ... } Lists: { "data": [...], "pagination": { "has_more": bool, "current_page": int } } Always access `.data`, not the root response. ## Common IDs Premier League: 8 | La Liga: 564 | Bundesliga: 82 | Serie A: 384 Champions League: 2 | World Cup 2026: league_id=732, season_id=26618 Topscorer types: goals=208, assists=209, yellow cards=84 ## Error handling 401/403 - invalid token or subscription restriction 404 - resource not found 429 - rate limit, back off and retry with exponential backoff ``` **2. Commit the file** ```bash git add .github/copilot-instructions.md git commit -m "Add Sportmonks API context for Copilot" ``` **3. Reload VS Code** Open the Command Palette → **Developer: Reload Window**. Copilot will pick up the new instructions. ### What changes Before the instructions file, Copilot might generate: ```typescript // Incorrect - wrong auth method and made-up endpoint const res = await fetch('https://api.sportmonks.com/fixtures', { headers: { Authorization: `Bearer ${token}` } }); ``` After the instructions file: ```typescript // Correct - proper endpoint and auth pattern const res = await fetch( `https://api.sportmonks.com/v3/football/fixtures/date/${date}?include=participants;scores;state&api_token=${process.env.SPORTMONKS_API_TOKEN}` ); ``` ### Copilot Chat You can also ask Copilot Chat directly and it will use the instructions as context: ``` @workspace Build a function that fetches live scores and returns an array of { home, away, score, state } ``` ``` @workspace Write a TypeScript client for the Sportmonks standings endpoint with proper error handling ``` # Windsurf Windsurf's Cascade agent supports MCP natively. Install the Sportmonks MCP server and Cascade has live access to all 11 tools - fetching real data mid-conversation as it writes your code. ### Prerequisites * [Node.js 18+](https://nodejs.org) * A Sportmonks API token from [my.sportmonks.com](https://my.sportmonks.com/subscriptions) * [Windsurf](https://codeium.com/windsurf) installed ### Setup **1. Add the MCP server to Windsurf** Edit `~/.codeium/windsurf/mcp_config.json` (create it if it doesn't exist): ```json { "mcpServers": { "sportmonks-football": { "command": "npx", "args": ["-y", "sportmonks-football-mcp-server"], "env": { "SPORTMONKS_API_TOKEN": "your_token" } } } } ``` Optional environment variables can be added to the `env` block: | Variable | Description | | ----------------------- | --------------------------------------------------------------------------------------------- | | `SPORTMONKS_LOG_FILE` | Path for the local tool-call log. Set to `off` to disable. Defaults to your OS temp directory | | `SPORTMONKS_DEBUG_URLS` | Set to `1` or `true` to log outbound API URLs to stderr (token redacted). Off by default | **2. Restart Windsurf** Open the Cascade panel - the Sportmonks tools will be available. ### Test it Open Cascade and ask: ``` Search for "Bayern Munich" and get their current squad ``` ``` Fetch today's fixtures and show me the ones that are live right now ``` ### Using context without MCP If you prefer not to install the server, paste the full context block at the start of your Cascade session. Cascade will use it to write accurate Sportmonks integration code, though it won't be able to fetch live data directly. # API Quick Nav ## Football API Endpoints ### Core & reference data Essential reference data used across the API. | Endpoint | Description | | -------------------------------------------------------------------------- | --------------------------------------------------- | | [Cities](https://docs.sportmonks.com/v3/core-api/endpoints/cities) | City information for venues and teams | | [Continents](https://docs.sportmonks.com/v3/core-api/endpoints/continents) | Continental regions | | [Countries](https://docs.sportmonks.com/v3/core-api/endpoints/countries) | Country data for leagues and teams | | [Filters](https://docs.sportmonks.com/v3/core-api/endpoints/filters) | Available filter options for queries | | [Regions](https://docs.sportmonks.com/v3/core-api/endpoints/regions) | Regional subdivisions within countries | | [Timezones](https://docs.sportmonks.com/v3/core-api/endpoints/timezones) | Timezone information for fixture scheduling | | [Types](https://docs.sportmonks.com/v3/core-api/endpoints/types) | Type definitions for statistics, events, and states | ### Live match data Real-time and fixture-related data. | Endpoint | Description | | -------------------------------------------------------------------------------------------- | ------------------------------------------------ | | [Commentaries](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/commentaries) | Live match commentary and text updates | | [Fixtures](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/fixtures) | Match fixtures with comprehensive data | | [Livescores](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/livescores) | Real-time scores for live matches | | [States](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/states) | Fixture state information (live, finished, etc.) | ### Teams & squads Team information and squad management. | Endpoint | Description | | ---------------------------------------------------------------------------------------------------- | --------------------------------------- | | [Team Squads](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/team-squads) | Current squad rosters for teams | | [Teams](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/teams) | Team profiles and information | | [Transfer Rumours](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/transfer-rumours) | Player transfer speculation and rumours | | [Transfers](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/transfers) | Player transfer history and records | ### Players & personnel Individual player and staff data. | Endpoint | Description | | ------------------------------------------------------------------------------------ | -------------------------------------- | | [Coaches](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/coaches) | Manager and coaching staff information | | [Players](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/players) | Player profiles and career data | | [Referees](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/referees) | Match official information | ### Competitions & seasons League and competition structures. | Endpoint | Description | | -------------------------------------------------------------------------------------- | ------------------------------------------ | | [Leagues](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/leagues) | Competition and league information | | [Rounds](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/rounds) | Matchday rounds within seasons | | [Schedules](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/schedules) | Season fixture schedules | | [Seasons](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/seasons) | Season data for leagues and competitions | | [Stages](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/stages) | Competition stages (group, knockout, etc.) | ### Statistics & performance Match and player statistics. | Endpoint | Description | | -------------------------------------------------------------------------------------------------------------- | -------------------------------------- | | [Aggregated Topscorers](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/aggregated-topscorers) | Combined topscorer data across seasons | | [Standings](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/standings) | League tables and rankings | | [Statistics](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/statistics) | Detailed match and player statistics | | [Topscorers](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/topscorers) | Leading scorers by competition | ### Predictions & analysis Advanced analytics and predictions. | Endpoint | Description | | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | | [Expected (xG)](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/expected-xg) | Expected goals and shot quality metrics | | [Predictions](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/predictions) | Match outcome predictions and probabilities | | [Premium Expected Lineups](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/premium-expected-lineups) | AI-predicted starting lineups | | [Rivals](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/rivals) | Historical rivalry data between teams | ### Beta features New features currently in beta testing. | Endpoint | Description | | --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | | [Match Facts](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/match-facts-beta) | Pre and post-match analysis and insights | | [Team of the Week (TOTW)](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/team-of-the-week-totw-beta) | Best-performing players each round | | [Team Rankings](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/team-rankings-beta) | Historical team ranking data | ### Odds & betting Betting markets and odds data. | Endpoint | Description | | -------------------------------------------------------------------------------------------------------- | ------------------------------------ | | [Bookmakers](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/bookmakers) | Betting bookmaker information | | [Markets](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/markets) | Betting market types and definitions | | [Premium Odds Feed](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/premium-odds-feed) | High-frequency premium odds data | | [Standard Odds Feed](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/standard-odds-feed) | Pre-match and in-play odds | ### Additional data Supplementary information and content. | Endpoint | Description | | ------------------------------------------------------------------------------------------ | --------------------------------- | | [News](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/news) | Pre and post-match news articles | | [TV Stations](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/tv-stations) | Broadcast information for matches | | [Venues](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/venues) | Stadium and venue details | ### Quick reference #### By use case **Building a livescore app?**\ Start with: [Livescores](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/livescores), [Fixtures](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/fixtures), [Events](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/events) **Building a statistics dashboard?**\ Start with: [Statistics](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/statistics), [Standings](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/standings), [Types](https://docs.sportmonks.com/v3/core-api/types) **Building a team profile page?**\ Start with: [Teams](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/teams), [Team Squads](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/team-squads), [Fixtures](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/fixtures) **Building a predictions platform?**\ Start with: [Predictions](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/predictions), [Expected (xG)](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/expected), [Trends](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/trends) **Building a fantasy football app?**\ Start with: [Players](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/players), [Statistics](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/statistics), [Fixtures](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/fixtures) ### All Endpoints (Alphabetical) **A** * [Aggregated Topscorers](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/aggregated-topscorers) **B** * [Bookmakers](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/bookmakers) **C** * [Cities](https://docs.sportmonks.com/v3/core-api/endpoints/cities) * [Coaches](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/coaches) * [Commentaries](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/commentaries) * [Continents](https://docs.sportmonks.com/v3/core-api/endpoints/continents) * [Countries](https://docs.sportmonks.com/v3/core-api/endpoints/countries) **E** * [Expected (xG)](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/expected-xg) **F** * [Filters](https://docs.sportmonks.com/v3/core-api/endpoints/filters) * [Fixtures](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/fixtures) **L** * [Leagues](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/leagues) * [Livescores](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/livescores) **M** * [Markets](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/markets) * [Match Facts (beta)](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/match-facts-beta) **N** * [News](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/news) **P** * [Players](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/players) * [Predictions](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/predictions) * [Premium Expected Lineups](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/premium-expected-lineups) * [Premium Odds Feed](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/premium-odds-feed) **R** * [Referees](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/referees) * [Regions](https://docs.sportmonks.com/v3/core-api/endpoints/regions) * [Rivals](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/rivals) * [Rounds](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/rounds) **S** * [Schedules](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/schedules) * [Seasons](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/seasons) * [Stages](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/stages) * [Standard Odds Feed](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/standard-odds-feed) * [Standings](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/standings) * [States](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/states) * [Statistics](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/statistics) **T** * [Team of the Week (TOTW) (beta)](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/team-of-the-week-totw-beta) * [Team Rankings (beta)](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/team-rankings-beta) * [Team Squads](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/team-squads) * [Teams](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/teams) * [Timezones](https://docs.sportmonks.com/v3/core-api/endpoints/timezones) * [Topscorers](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/topscorers) * [Transfer Rumours](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/transfer-rumours) * [Transfers](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/transfers) * [TV Stations](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/tv-stations) * [Types](https://docs.sportmonks.com/v3/core-api/endpoints/types) **V** * [Venues](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/venues) ### Need Help? * 📚 [Getting Started Guide](https://docs.sportmonks.com/v3/welcome/getting-started) * 🎓 [Tutorials](https://docs.sportmonks.com/v3/football/tutorials) * ❓ [FAQ](https://docs.sportmonks.com/v3/faq) * 📧 Support: # API Coach Welcome to the documentation for our new API Coach, a conversational assistant that does more than chat; it coaches you through authentication, rate‑limits, response structures and best practices.

### 1. Purpose of this page This guide explains how to access the API Coach, what it can do today, its known limitations, and how your feedback can help us improve it. ### 2. Key benefits at a glance * 24 / 7 availability! Instant answers any time. * Personalised guidance. Responses adapt to your account and context. * Embedded help. No need to open a ticket or leave the page. Access to resources, direct links to docs, tutorials and FAQS. ### 3. Getting started 1. Visit [MySportmonks.com](https://my.sportmonks.com/dashboard) 2. Click the persistent chat bubble in the bottom‑right corner. 3. Type a question (e.g. “How do I integrate the API?”) and press Enter. 4. The API Coach responds immediately; follow any suggested links or buttons. 5. To end the session, simply close the chat window. ### 4. What can you ask currently? The API Coach can currently help with: * Troubleshooting common error messages. * Questions about which API requests to make and which docs pages to use for common queries. * Best‑practice recommendations. * Links to detailed guides and tutorials. Feel free to experiment. If the API Coach cannot complete a request, you can click on ‘thumbs down’. We will then receive a message about the inaccurate or incomplete query. Then you can contact for further assistance. ### 5. Known limitations * Does not yet support account-specific actions, such as password resets or viewing billing information. * English language only; multilingual support is planned. * May occasionally provide incomplete or overly broad answers; please use the “thumbs‑down” button to flag these. Knowledge cutoff: Product changes made after April 2025 may not be reflected. ### 6. Providing feedback Feedback is a gift, and we appreciate you taking the time to help us grow and learn from your experience!\ \ Your insights directly shape our roadmap. You can: * Click on the “thumbs‑down” button to flag inaccurate/incomplete answers. This way, you provide us with valuable feedback about the responses. We review all feedback on a weekly basis and publish progress updates on the Changelog page.
### 7. Data privacy & security * We store chat history for a limited period to improve quality; you may request its deletion at any time. * Never share sensitive personal data (credit‑card numbers, passwords, etc.) with the API Coach. * All of our APIS require authentication. You can create API tokens in MySportmonks. You need to be authenticated before making your first request. We offer two different options for passing your API token. You are free to choose between the authentication methods, and you can use both simultaneously. Please note that both methods count towards the same rate-limiting. 1. Authenticate using a query parameter. * You can pass your API token by passing 'api\_token' in your request parameters, like so: 2. Authenticate using a request header. * You can also pass your token via an 'Authorisation' header, like so:

You can obtain and manage your API token in[ MySportmonks.](https://my.sportmonks.com/api/tokens) The API token is meant for your eyes only and, as such, should be stored securely. Our tokens have no expiration date and will remain valid until you manually delete them yourself. ### 8. Frequently asked questions Q: Is the API Coach replacing human support?\ A: No. The API Coach handles routine queries, allowing our specialists to focus on more complex issues. Q: How accurate are the answers?\ A: Our internal testing shows ≈90 % accuracy on covered topics. Your feedback helps us close the gap. ### 9.  Need help? If you have questions that this guide does not cover, reach out to . Thank you for using the API Coach and helping us build a better API Coach experience for everyone! # Changelog Since the release of API3 and onwards, we will list any additions and changes made in the API on this page, in chronological order (YYYY-MM-DD format) ### 2026-05-27 **Delay and break timeline events** Two new timeline event types have been added to track match delays and scheduled breaks, such as hydration breaks and cooling breaks. | Type | `type_id` | Description | | ------------- | --------- | ---------------------------------------- | | `DELAY_START` | `132791` | Recorded when a delay or break begins | | `DELAY_END` | `132792` | Recorded when play resumes after a break | Both types appear on the `timeline` include and follow the same structure as other event records. The `info` field on a `DELAY_START` record describes the reason for the break where available (e.g. `"Hydration break"`). `DELAY_END` records always return `null` for `info`. Each delay produces one record per participant, so expect two `DELAY_START` records and two `DELAY_END` records per break - one for each team's `participant_id`. {% hint style="info" %} This feature is currently being rolled out to select competitions. Initial 'Hydration break' coverage includes the FIFA Club World Cup and FIFA World Cup 2026. For full documentation, see [Hydration Breaks](https://docs.sportmonks.com/v3/world-cup-2026/hydration-breaks). Additionally, delay events are being rolled out to our Free Plan leagues (Danish Superliga and Scottish Premiership), with more leagues following later on. {% endhint %} ### 2026-05-21 **Improved API error messages** Four improvements have been made to API error responses to make debugging faster and more precise. **Selecting a field that is a relationship now returns a specific error** Previously, passing a relationship name to `select` returned a generic error. The response now clearly indicates that the field is a relationship and should be used with `include` instead. ``` GET /v3/football/teams/3468?include=coaches&select=coaches ``` ```json // Before "message": "You made an incorrect request, please check your includes and filters, they probably contain invalid arguments or syntax." // After "message": "The select field 'coaches' is a relationship, not a column. Use the 'include' parameter to load related data.", "link": "https://docs.sportmonks.com/football/api/response-codes/filtering-and-complexity-exceptions" ``` **Combining a locale with an include no longer returns an error** Using `locale` alongside `include` on endpoints such as `/v3/football/players/latest` was incorrectly returning an error. This has been resolved and both parameters now work together as expected. ``` GET /v3/football/players/latest?include=nationality&locale=es ``` **Including a non-existent field now returns a specific error** Previously, requesting a field that does not exist on an included resource returned a generic error. The response now names the offending field directly. ``` GET /v3/football/fixtures/between/2024-01-01/2026-05-20/14?include=participants:name,short_code,meta ``` ```json // Before "message": "You made an incorrect request, please check your includes and filters, they probably contain invalid arguments or syntax." // After "message": "The field 'meta' does not exist on the included resource.", "link": "https://docs.sportmonks.com/football/api/response-codes/filtering-and-complexity-exceptions" ``` **Selecting a non-existent field now returns an error** Previously, passing an unknown field name to `select` returned a normal response silently ignoring the field. It now returns an explicit error. ``` GET /v3/football/fixtures/19172201?select=detailed_state_id ``` ```json // Before {....normal response....} // After "message": "The select field 'detailed_state_id' does not exist on this resource.", "link": "https://docs.sportmonks.com/football/api/response-codes/filtering-and-complexity-exceptions" ``` ### 2026-04-22 A new fixture lineup statistic type is available: `CUMULATIVE_MINUTES_PLAYED`. This is a statistic similar to `MINUTES_PLAYED`, however, there are a few key differences: * Cumulative minutes played always include the period added/injury time * Cumulative minutes played always include the time played in extra time periods * Cumulative minutes played have an improved live update speed over the regular minutes played ### 2026-03-26 For API performance reasons, we have removed the `odds` and `premiumOdds` includes from our [Livescores endpoints](/v3/endpoints-and-entities/endpoints/livescores). These includes made the Livescores endpoints large and slow, and caused timeout issues during peak hours due to the amount of fixtures returned, including their odds. As these includes return pre-match odds specifically, no updates are made to the returned odds after kick-off. {% hint style="success" %} Endpoints other than the Livescores endpoints are **not** affected by this change.\ The `inplayOdds` include is also **not** affected by this change. {% endhint %} We recommend to use alternative endpoints or includes instead, for example: * [GET Last Updated Odds](/v3/endpoints-and-entities/endpoints/standard-odds-feed/pre-match-odds/get-last-updated-odds) (Standard Odds) * [GET Updated Premium Odds Between Time Range](/v3/endpoints-and-entities/endpoints/premium-odds-feed/premium-pre-match-odds/get-updated-premium-odds-between-time-range) (Premium Odds) * Using same include on [GET Fixture by ID](/v3/endpoints-and-entities/endpoints/fixtures/get-fixture-by-id) or [GET Fixtures by Multiple IDs](/v3/endpoints-and-entities/endpoints/fixtures/get-fixtures-by-multiple-ids) ### 2026-03-09 We’ve launched a new pricing structure for designed to make our platform easier to use, more flexible, and better aligned with how developers actually build sports applications. This update is based on extensive feedback from customer interviews and conversations with our community. The goal is simple: give you more control over what you pay for while keeping access to our full data platform straightforward. Below is an overview of what has changed. #### The new setup We now offer four core plans:

Plan	Leagues	API Calls	Price
Starter	5 leagues	2,000/hour	€29/month
Growth	30 leagues	2,500/hour	€99/month
Pro	120 leagues	3,000/hour	€249/month
Enterprise	All leagues	5,000/hour	Custom

The key difference between plans is **scale**, not feature access. Plans determine: * The number of leagues you can include * Your API call capacity * Support level and flexibility All plans come with a **14-day free trial**, and yearly billing includes a **20% discount**. For more information please refer to our [blog](https://www.sportmonks.com/blogs/introducing-our-new-pricing-setup/). ### 2026-01-28 We’ve added support for [**Knockout Tournament Brackets**](/v3/endpoints-and-entities/endpoints/seasons/get-brackets-by-season-id).\ This new feature allows competitions such as cups and playoff stages to be represented as a true bracket structure, where matches are linked to each other based on progression (for example: *Winner of Match A vs Winner of Match B*).\ With this update: * Knockout stages (Round of 16, Quarter-finals, Semi-finals, Final, Third-place playoff) can be followed end-to-end * For each match, you can determine on what earlier matches it depends on, and whether the winner or loser progresses * Brackets can be visualised clearly in front-end applications * Placeholder fixtures automatically resolve as results become available This makes it easier to build accurate bracket views, follow tournament progression, and react to results in real time. {% hint style="info" %} Note that this functionality is only available for eligible leagues. It is not available for every domestic or international cup at this moment. {% endhint %} {% code expandable="true" %} ```javascript { "data": { "stages": [ { "stage_id": 77479086, "stage_name": "16th Finals", "fixtures": [ { "id": 19606960, "sport_id": 1, "league_id": 732, "season_id": 26618, "stage_id": 77479086, "group_id": null, "aggregate_id": null, "round_id": null, "state_id": 1, "venue_id": 343444, "name": "2nd position Group A vs 2nd position Group B", "starting_at": "2026-06-28 19:00:00", "result_info": null, "leg": "1/1", "details": "Match 73", "length": 90, "placeholder": true, "has_odds": false, "has_premium_odds": false, "starting_at_timestamp": 1782673200 }, // More fixtures... ] }, // More knockout stages... ], "edges": [ { "id": 13, "season_id": 26618, "child_fixture_id": 19606961, "child_slot": "home", "parent_fixture_id": 19606950, "parent_outcome": "winner" }, { "id": 14, "season_id": 26618, "child_fixture_id": 19606961, "child_slot": "away", "parent_fixture_id": 19606947, "parent_outcome": "winner" }, // More edges... ``` {% endcode %} ### 2025-11-19 We've introduced a new metadata type, *Pressure Status*, to the Fixture entity. This metadata provides an indicator named *computable* to indicate if the Pressure Index could accurately be computed. If there are too few statistics available in the trends to generate an accurate Pressure Index, the value of *computable* will be *false*, and there will be no Pressure Index available for that fixture. ```json // https://api.sportmonks.com/v3/football/fixtures/?include=metadata.type "metadata": [ // ... { "id": 8754935, "metadatable_id": 19600130, "type_id": 97352, "value_type": "object", "values": { "computable": true }, "type": { "id": 97352, "name": "Pressure Status", "code": "pressure-status", "developer_name": "PRESSURE_STATUS", "model_type": "metadata", "stat_group": null } } ] ``` ### 2025-11-10 We've made a change that adds the `player_id` and `type_id` fields, as well as `sidelined.player` and `sidelined.type` includes to the fixture `sidelined` include. This change makes it possible for per-fixture injury data to appear and to improve the base coverage, as the data `sidelined.sideline` represents a more detailed injury dataset. For example, if the start and end dates of the injury are not available (which is visible in the sidelined.sideline include), the available sidelined data will be shown directly under the `sidelined` include, and the `sidelined.sideline` include will not show data for that item.

{
    "data": {
    "id": 12345678,
    "name": "Team A Name vs Team B Name",
    "starting_at": "2025-11-10 12:00:00",
    "sidelined": [ // sidelined include
        {
            "id": 123456,
            "fixture_id": 12345678,
            "sideline_id": null, // will be null for this item
            "participant_id": 12345,
            "player_id": 67890, // new field
            "type_id": 339, // new field
            "sideline": null, // sidelined.sideline include: not available for this item
            "participant": {
                "id": 12345,
                "name": "Team A Name",
                // ...
            },
            "player": { // new player include
                "id": 67890,
                "common_name": "F. Lastname",
                "firstname": "Firstname",
                // ...
            },
            "type": { // new type include
                "id": 339,
                "name": "Groin Injury",
                "code": "groin-injury",
                "developer_name": "GROIN_INJURY",
                "model_type": "injury_suspension",
                "stat_group": null
            }
        }
        // ...
    ],

### 2025-08-19 We’ve expanded match facts to include more granular statistics and standardised naming across categories. Since we are still in the beta phase, this change only applies to the upcoming matches. \ Category `h2h` * **Added:** `MATCH_FACT_LAST_5_{STAT}`, `MATCH_FACT_LAST_10_{STAT}`, `MATCH_FACT_LAST_15_{STAT}`, `MATCH_FACT_LAST_25_{STAT}` * **Unchanged:** existing `MATCH_FACT_{STAT}` types (which still refer to *all* historical H2H matches between the teams) Category `overall` * **Previously:** facts for the last 10 matches were supplied as `MATCH_FACT_{STAT}` (e.g. `MATCH_FACT_GOALS`) * **Now:** supplied as `MATCH_FACT_LAST_10_{STAT}` (e.g. `MATCH_FACT_LAST_10_GOALS`) {% hint style="danger" %} Breaking change: the old `MATCH_FACT_{STAT}` is no longer supported in the `overall` category {% endhint %} **Affected stats**\ The following `{STAT}` values are affected in both categories: * `WIN` * `DRAW` * `LOSS` * `CLEANSHEET` * `GOALS` * `GOALS_CONCEDED` * `CORNERS` * `REDCARDS` * `YELLOWCARDS` * `YELLOWRED_CARDS` * `SHOTS_TOTAL` * `SHOTS_ON_TARGET` * `FIRST_TO_SCORE` * `GOAL_LINE` * `BTTS` * `WINNING_MARGIN` * `CARDS_COUNT` * `GOAL_TIMINGS` * `CARDS_COUNT_IN_MATCH` ### 2025-06-30 We've introduced a new field, *rescinded*, to the [Event](/v3/definitions/types/events) entity. This field provides a boolean indicator for card events: *true* if the referee has rescinded the card or *false* if the card still counts. For other events (or historical card events where this information is not available yet), the field will be *null*. ```json { "id": 149899270, "fixture_id": 19134999, "period_id": 6007175, "participant_id": 52, "type_id": 20, "section": "event", "player_id": 11298616, "related_player_id": null, "player_name": "Evanilson", "related_player_name": null, "result": null, "info": "Foul", "addition": "1st Redcard", "minute": 70, "extra_minute": null, "injured": null, "on_bench": false, "coach_id": null, "sub_type_id": null, "detailed_period_id": 6007175, "rescinded": true, <- Rescinded card "sort_order": 1 } ``` ### 2025-03-10 Two new filters have been added to the API for enhanced flexibility and customization: * **HavingPremiumOdds** filter\ Allows users to filter out any fixtures not having premium odds available. Similar to the *havingOdds* filter for out default odds field. The filter can be applied on fixture entities. ``` api.sportmonks.com/v3/football/fixtures/date/2025-03-10?filters=havingPremiumOdds&api_token=TOKEN ``` * **Gender** filter\ Enables users to filter **teams** or **players** based on a specific gender (`male`, `female`, or `null`). If a player's gender is (yet) unknown, it is assigned a default value of `null`. ``` api.sportmonks.com/v3/football/teams?filters=genders:female&api_token=TOKEN ``` ### 2025-01-22 With the release of our new data-processing logic, we’ve introduced new types to better distinguish between extra time periods and their individual halves. Previously, there was only a single period type for extra time: ET (type\_id: 3). Now, extra time has been separated into two distinct types: * **ET\_1ST\_HALF** (type\_id: 5314) * **ET\_2ND\_HALF** (type\_id: 39). To take advantage of these improvements, a new API include called **`detailedPeriods`** has been added. This include provides detailed information about periods, including the separation of extra time into its two halves. In addition, **events** now include a `detailed_period_id`, which points to the corresponding `detailedPeriod`. We strongly encourage all users to adopt this new structure to ensure greater consistency and accuracy in your applications.\ \ In the near future, we will make every effort to back populate historical fixtures with these detailed periods, to provide a more seamless experience with periods. {% tabs %} {% tab title="DetailedPeriods" %} ```json "detailedperiods": [ { "id": 5811911, "fixture_id": 19353646, "type_id": 1, "started": 1736884878, "ended": 1736887852, "counts_from": 0, "ticking": false, "sort_order": 1, "description": "1st-half", "time_added": 2, "period_length": 45, "minutes": 49, "seconds": 34, "has_timer": false }, { "id": 5812022, "fixture_id": 19353646, "type_id": 2, "started": 1736888773, "ended": 1736891833, "counts_from": 45, "ticking": false, "sort_order": 2, "description": "2nd-half", "time_added": 6, "period_length": 45, "minutes": 96, "seconds": 0, "has_timer": false }, { "id": 5813446, "fixture_id": 19353646, "type_id": 39, "started": 1736893340, "ended": 1736894412, "counts_from": 105, "ticking": false, "sort_order": 4, "description": "extra-time-2nd-half", "time_added": 1, "period_length": 15, "minutes": 122, "seconds": 52, "has_timer": false }, { "id": 5813445, "fixture_id": 19353646, "type_id": 5314, "started": 1736888773, "ended": 1736889673, "counts_from": 90, "ticking": false, "sort_order": 3, "description": "extra-time-1st-half", "time_added": null, "period_length": 15, "minutes": 105, "seconds": 0, "has_timer": false } ], ``` {% endtab %} {% tab title="Periods (legacy)" %} ```json "periods": [ { "id": 5811911, "fixture_id": 19353646, "type_id": 1, "started": 1736884878, "ended": 1736887852, "counts_from": 0, "ticking": false, "sort_order": 1, "description": "1st-half", "time_added": 2, "period_length": 45, "minutes": 49, "seconds": 34, "has_timer": false }, { "id": 5812022, "fixture_id": 19353646, "type_id": 2, "started": 1736888773, "ended": 1736891833, "counts_from": 45, "ticking": false, "sort_order": 2, "description": "2nd-half", "time_added": 6, "period_length": 45, "minutes": 96, "seconds": 0, "has_timer": false }, { "id": 5813447, "fixture_id": 19353646, "type_id": 3, "started": 1736893340, "ended": 1736894412, "counts_from": 105, "ticking": false, "sort_order": 4, "description": "extra-time", "time_added": 1, "period_length": 15, "minutes": 122, "seconds": 52, "has_timer": false } ] ``` {% endtab %} {% tab title="Updated Event Object" %} ```json { "id": 148734119, "fixture_id": 19353646, "period_id": 5813447, <- Legacy field, refers to legacy period "participant_id": 1652, "type_id": 16, "section": "event", "player_id": 37583848, "related_player_id": null, "player_name": "Richie Omorowa", "related_player_name": null, "result": "5-4", "info": "Penalty", "addition": "9th Penalty", "minute": 117, "extra_minute": null, "injured": null, "on_bench": false, "coach_id": null, "sub_type_id": 16, "detailed_period_id": 5813446, <- Added field, refers to detailedPeriod "sort_order": 9 } ``` {% endtab %} {% endtabs %} ### 2024-11-04 We've introduced a new metadata type, *Prediction Status*, to the Fixture entity. This metadata provides an indicator named *predictable* to indicate if the prediction model could accurately make fixture predictions. If the model can't make accurate fixture predictions, the value of *predictable* will be *false*, and there will be no predictions available for that fixture. ```json // https://api.sportmonks.com/v3/football/fixtures/19134873?include=metadata.type "metadata": [ // ... { "id": 6882438, "metadatable_id": 19134873, "type_id": 37072, "value_type": "object", "values": { "predictable": true }, "type": { "id": 37072, "name": "Prediction Status", "code": "prediction-status", "developer_name": "PREDICTION_STATUS", "model_type": "metadata", "stat_group": null } } ] ``` ### 2024-09-30 A new include call ***rankings*** has been added to the API. You may use this include on a Team to get information about the coefficient rankings for the desired team. We continue to expand our coverage regarding these rankings.

// https://api.sportmonks.com/v3/football/teams/8?include=rankings

"rankings": [
    {
        "id": 10,
        "position": 4,
        "participant_id": 8,
        "points": 98000,
        "sport_id": 1,
        "type": "UEFA"
    }
]

### 2024-09-10 We've introduced a new field, *sort\_order*, to the [Event](/v3/definitions/types/events) entity. This field provides a numerical ranking system to determine the chronological order of events within a specific type. {% tabs %} {% tab title="Updated response" %} ```json { id: 120221102, fixture_id: 19296203, period_id: 5606524, participant_id: 8, type_id: 14, section: "event", player_id: 1743, related_player_id: 84627, player_name: "Virgil van Dijk", related_player_name: "Konstantinos Tsimikas", result: "1-2", info: "Header", addition: "3rd Goal", minute: 41, extra_minute: null, injured: null, on_bench: false, coach_id: null, sub_type_id: null sort_order: 3 <- Assigned per type_id }, ``` {% endtab %} {% tab title="Previous response" %} ```json { id: 120221102, fixture_id: 19296203, period_id: 5606524, participant_id: 8, type_id: 14, section: "event", player_id: 1743, related_player_id: 84627, player_name: "Virgil van Dijk", related_player_name: "Konstantinos Tsimikas", result: "1-2", info: "Header", addition: "3rd Goal", minute: 41, extra_minute: null, injured: null, on_bench: false, coach_id: null, sub_type_id: null }, ``` {% endtab %} {% endtabs %} By assigning a unique sort order to each event within a type, users can more easily organize and display events in a sequential manner based on their occurrence. This feature allows for a more intuitive and efficient way to identify, browse and filter events. ### 2024-08-11 We're excited to announce new enhancements to our xG statistics, now available at the season level! For both [players](/v3/tutorials-and-guides/tutorials/statistics/players-statistics) and [teams](/v3/tutorials-and-guides/tutorials/statistics/team-statistics), you can now track their xG Over/Under performance throughout the entire season. This feature reveals how teams and players are actually performing compared to their expected goals (xG) :bar\_chart: Additionally, we've introduced the Expected Points table to our [standings details](/v3/tutorials-and-guides/tutorials/standings/season-standings). This new feature lets you compare a team's overall performance against their expected points, offering deeper insights into their season :eyes:\ \ These new features are available for all of our customers having an xG standard or advanced package in their subscription :fire::soccer: ### 2024-05-12 We're excited to announce the launch of Expected Goals (xG) metrics in the Sportmonks API! With the addition of xG data, users can now access valuable insights into goal-scoring probabilities, enhancing their football analysis and decision-making processes. **What's New?** * [**xG Types**](/v3/definitions/types/expected#expected-types): Explore detailed Expected Goals (xG) metrics, including Expected Goals (xG) and Expected Goals on Target (xGoT), for teams and players participating in football matches. * [**New Endpoints**](/v3/endpoints-and-entities/endpoints/expected-xg): Discover new endpoints, such as `v3/football/expected/fixtures` and `v3/football/expected/lineups`, specifically designed to retrieve xG data per team or player lineup. ### 2024-04-05 * Added new [statistics types](/v3/definitions/types/statistics) for teams on seasonal level: Card Per Foul, Shot On Target Percentage, Shot Conversion Rate, Penalty Conversion Rate, Most Injured Players, Most Substituted Players, Appearing Players, Average Points Per Game, Players Footing, Amount Of Foreigners, Average Player Age, and Average Player Height. ### 2024-03-21 * Periods now show the elapsed *minute* and *seconds* even though a period is no longer *ticking*. ### 2024-02-26 * Introducing the ability to perform custom sorting on Sportmonks API3 endpoints! With this enhancement, users can now include the `sortBy` parameter to sort base entities in ascending or descending order. The feature supports sorting on fields like `starting_at` and `name` for fixtures, providing users with greater flexibility in organising and retrieving data. You can find more information on the dedicated [sorting](/v3/api/request-options/ordering-and-sorting#custom-sorting) page. ### 2023-11-27 * An endpoint to retrieve [extended squad details](/v3/endpoints-and-entities/endpoints/team-squads/get-extended-team-squad-by-team-id) has been added. This endpoint shows all players that were active in the current seasons for the team. If a player is no longer part of the squad or is currently a youth team player, the *in\_squad* field is marked false. * Periods now contain a *has\_timer* attribute. It marks whether we have detailed timer information for *minutes* and *seconds* attributes available. * Minor updates and optimisations to our back-end infrastructure. ### 2023-11-13 * Historical records and value changes are now available for the Premium Odds Feed. They are available via the *history* include (updates since 5 minutes ago) on PremiumOdd records, or via the respective [All](/v3/endpoints-and-entities/endpoints/premium-odds-feed/premium-pre-match-odds/get-all-historical-odds) and [Updated](/v3/endpoints-and-entities/endpoints/premium-odds-feed/premium-pre-match-odds/get-updated-historical-odds-between-time-range) endpoints (all updates). * An endpoint that lists all the [supported timezones](/v3/core-api/endpoints/timezones/get-all-supported-time-zones) has been added. * Passing your preferred time zone now also has direct effect on the query results on the [League By Date](/v3/endpoints-and-entities/endpoints/leagues/get-leagues-by-fixture-date) endpoint. ### 2023-10-30 * Due to a deviation in the aggregation of API3 request logs, we have cleared the tables records and added a fix for the behaviour. The [API usage](/v3/core-api/my-sportmonks/get-my-usage) endpoint now returns the correct results again. ### 2023-09-21 * A new event type has been implemented which tracks VAR checks related to cards. From today onwards all VAR events that are related to cards are covered under the VAR\_CARD event type.

Example

```javascript { "id": 90673921, "fixture_id": 18867346, "period_id": 4993000, "participant_id": 7790, "type_id": 1697, "section": "event", "player_id": 435939, "related_player_id": null, "player_name": "Federico Baschirotto", "related_player_name": null, "result": null, "info": null, "addition": "Redcard confirmed", "minute": 56, "extra_minute": null, "injured": null, "on_bench": false, "coach_id": null, "sub_type_id": null, "type": { "id": 1697, "name": "VAR_CARD", "code": "VAR_CARD", "developer_name": "VAR_CARD", "model_type": "event", "stat_group": null } }, ```

### 2023-09-13 * An endpoint for insights into your [API usage](/v3/core-api/my-sportmonks/get-my-usage) has been added. This endpoint will return your usage aggregated per endpoint per 5 minutes. \ \ You may for example use this endpoint to build your own monitoring dashboards, or to gain insights into how you can optimize your traffic to our API by spreading your usage. 📊💻 ### 2023-09-06 * Both Referee and Coach entities now offer the possibility to add the *latest* include. The include providers their latest fixtures records from the past 6 months. ### 2023-09-04 * When available, a *code* field has been added to the API error response, these errors include a link to our documentation pages where the errors are explained more briefly. The *code* corresponds to one of the entries in the listed table.

Errors now contain a *code* attribute when available.

* When using the *statistics* include on a Season, using the nested Type include caused the original *type* field for the object to be overridden. To prevent this behaviour from happening, the relational Type object will now be available under the *statistic\_type* attribute.

Type object now available under *statistic_type* attribute.

### 2023-08-15 * TV station BT Sport has been renamed to TNT Sports due to rebranding. (affecting ID 46 and 860). TNT Sports 2, 3, 4 are newly added under ID 928, 929, 930. ### 2023-07-18 * Filtering on id's on "All Endpoints" has now been added. You can use it to only request the entities of which the id is one of the given values. You need pass the name of the desired entity to apply the filters on. See the examples below for reference:\ \
* We have added the possibility to filter on active seasons when requesting statistics. You can pass the *currentSeasons* filter to leverage this functionality, make sure to pass the desired Entity to apply the filter on as well, check the example below for reference, this will only return. you statistics for current / active seasons that belong to players in the response:\
* An *is\_captain* indicator has been added for Squads. Showing *true* if the player is currently the default captain for the regarding squad. * Using filters that allow you to pass id's, now support a maximum of 50 records. This reflects the maximums (*per\_page)* we allow on default paginated endpoints. ### 2023-06-08 * Endpoints for retrieving [statistics](/v3/endpoints-and-entities/endpoints/statistics) have been added. These allow you to easily retrieve statistics for specific seasons, stages, or rounds, instead of having to propagate through includes to retrieve them. * A new include called '*currentPeriod'* has been added. It allows for retrieval of the inplay period in a more convenient way compared to using the *periods* include. Please note the include may return *NULL.* For example when the match has not yet started, is in half-time, or has ended. * The PlayerStatistic entity now contains a *has\_values* field, indicating whether a Player has any statistics available for the given season. * We have renamed the BEATS type to SUCCESSFUL\_DRIBBLES to better reflect the type of statistic. {% embed url="" %} A tutorial which covers all the new features added with this release {% endembed %} ### 2023-05-31 * Two new endpoints have been added, one for retrieving [upcoming Fixtures by tv-station id](/v3/endpoints-and-entities/endpoints/fixtures/get-upcoming-fixtures-by-tv-station-id), and one for retrieving [past Fixtures by tv-station id](/v3/endpoints-and-entities/endpoints/fixtures/get-past-fixtures-by-tv-station-id). If you have tv-stations available in your subscription, you automatically have access to these endpoints. ### 2023-05-30 * We have added the *currentPeriod* include. You can use this as a more convenient way to get the current inplay period for a fixture. Note that the result can be *null,* for example when the fixture itself is not inplay or the fixture is currently in half-time break. ### 2023-05-17 * The [Multiple Fixtures by Id](/v3/endpoints-and-entities/endpoints/fixtures/get-fixtures-by-multiple-ids) endpoint now allows a maximum of 50 unique id's, this reflects the maximums (*per\_page)* we allow on default paginated endpoints. ### 2023-04-28 * The developer name of Type "Screwsnails Removal" (id: 830) has been renamed to SCREWS\_NAILS\_REMOVAL for naming convention. ### 2023-04-18 As per an earlier announcement, we have released some changes to the API on this date. #### Removed fields: * **State**: *is\_live, is\_pending, is\_period\_end, is\_final\_state, is\_cancelled, is\_final\_standing\_state, is\_completed, type\_id, is\_deleted, is\_notstarted, period\_length\_setting, deactivate\_inplay* * **Period*****:** period\_length\_internal, final\_minute, home\_score, away\_score* * **Fixture:** *last\_processed\_at* #### Renamed fields: * **Squad:** *yersey\_number was* renamed to *jersey\_number* **Added fields:** * **League:** *category (*basic tier like indicator for the size / popularity of the league. Ranges from 1-4, where 1 are the most 'popular' leagues. **Ordering on endpoints:** * Paginated endpoints now support [ordering](/v3/api/request-options/ordering-and-sorting), you can pass a query parameter *order* with your request to indicate the desired order. Currently *order=desc* and *order=asc* are supported. Visit the documentation of the endpoint you are wishing to use ordering on to obtain the field that the ordering applies on. ```url https://api.sportmonks.com/v3/football/fixtures?api_token=YOUR_TOKEN&page=2&order=desc ``` **Threshold adjustments:** * The threshold of the [Latest Updated Fixtures ](/v3/endpoints-and-entities/endpoints/fixtures/get-latest-updated-fixtures)endpoint was lowered from 5 minutes, to 10 seconds. The previous threshold of 5 minutes fetched too much results at times, causing requests to time out. # Changelog (BETA) {% hint style="info" %} This changelog was used during the Beta version of API3. Since API3 has been released by now, this Beta changelog will no longer be updated. You should refer to the [live changelog ](/v3/changelog/changelog-1)instead. {% endhint %} From the 25th of October and onwards, we will list any additions and changes made in the API (Beta) on this page, in chronological order (**YYYY-MM-DD format)**. ### 2023-04-03 * We have added a new type called GOALKEEPER\_GOALS\_CONCEDED. This was required because the current GOALS\_CONCEDED stat merged the goalskeeper and player stats which was not mean to be. ### **2023-03-07** * We have changed some logic in the parsing of includes, making them case-insensitive. As a result of this the response will also include a lowercase contiguous version of the include name. ### **2023-02-24** * For the time being, we have removed the player\_id and related\_player\_id fields from comments, they will be added back again at a later stage, after the implementation for the detection of players names has been further improved. ### **2023-02-17** * We have implemented a filter called *hasOdds* on Fixture entities. You can apply it like so *\&filters=havingOdds* You can also switch the value of the boolean to check for, use *\&filters=havingOdds:false* to get the exact opposite results. * A field called *has\_odds* has been implemented on Fixture entities, marking whether a Fixture has odds available in our database. ### **2023-02-13** * When using the *topscores* include on Stages and Seasons, you can now use a nested *topscorer (e.g topscorers.topscorer)* include, this include shows more information about how the record was established, for example for a player, it shows for which individual teams the player scored goals for which counted towards the total. ### **2023-02-10** * New Bookmakers have been added; MelBet, Macauslot and HG * Odds processing for Betregal, Ladbrokes, Cloudbet, Nitrogen, Betclic and MansionBet has been implemented. ### **2023-02-06** * The endpoints returning "all" entities, are now ordered by their respective ID in ascending order. ### **2023-01-31** * When using the *participants* include on a [Fixture](/v3/endpoints-and-entities/entities/fixture). The meta now shows the *winner* and *position* field, respectively indicating whether a participant has won the fixture, and the position of the participant in the league's standings prior to the match. ### **2023-01-18** * Since we have drastically changed our pre-match odds processing for API3, pre-match odds are now updating more frequently, causing any changes in odds values to be available a lot quicker than before. Therefore, we have changed the threshold of [Latest Updated Pre-Match](/v3/endpoints-and-entities/endpoints/standard-odds-feed/pre-match-odds/get-last-updated-odds) odds endpoint from 5 minutes to 10 seconds, since using the 5 minute threshold could cause memory issues because of the amount of updated odds returned. ### **2023-01-13** * The *statistics* include is now available on [Rounds](/v3/endpoints-and-entities/endpoints/rounds), [Stages](/v3/endpoints-and-entities/endpoints/stages), and [Periods](/v3/endpoints-and-entities/entities/fixture). * A *Socials* include has been added to retrieve the Social Media platforms a team / player etc. is active on. In addition a *Channels* include has been added to retrieve extended information about the social media platform. We hope to expand our coverage of these socials over time. ![](/files/ETBLr7h2pO7Bf9XMkrIu) ### **2023-01-11** * We will be reloading the (historical) pre-match odds for API3. Until the process is done the coverage of the odds for API3 may vary. *Update: this process is now completed.* ### **2023-01-04** * We will be reloading the (historical) pre-match odds for API3. Until the process is done the coverage of the odds for API3 may vary. *Update**:** this process is now completed.* * A *subType* include has been added, this include gives additional information about a certain entity which also belongs to a type. For example on Events, the *type\_id* can be of *GOAL* (id: 14), the *sub\_type* can give more information about this event, for example that the goal was with a *RIGHT\_FOOT\_SHOT* (id: 1522). ![](/files/6eb0p6tzIIQdVSeGaNkX) * The *home\_score* and *away\_score* on Fixtures and Periods have now been removed from the API, they were deprecated as stated in the changelog entry from **2022-12-23**. ### **2022-12-23** * A *scores* include has been added to retrieve a score for fixtures in a more convenient way. The include returns the scores per period, as well as the current score for the regarding fixture. \ The *home\_score* and *away\_score* on a Fixture are now deprecated, as well as these fields on a Period, they will be removed from the API in before the beta stage is over. ### **2022-12-19** * The *Current Leagues by Team Id* and the *Leagues by Team Id* endpoint have been moved from the */teams* route directory to the */leagues* route directory, this better follows the convention since a league is the base entity that is returned. ### **2022-12-15** We are currently load testing the API. The availability and performance of the API may vary while this is ongoing. ### **2022-12-06** * The [Live Leagues](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/leagues/get-leagues-by-live) and [Leagues by Fixture Date](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/leagues/get-leagues-by-fixture-date) endpoints now use league priority. * A *metadata* include has been added to [Player](/v3/endpoints-and-entities/endpoints/players) entities, it gives additional information about a player, for example their preferred foot. * A *position* include has been added to [PlayerStatistic](/v3/endpoints-and-entities/entities/statistic) entities. * We will be reloading the pre-match odds for API3. Fixtures can return empty lists for pre-match orders until the reload is complete. Once the reload is completed, it will be stated here. ### **2022-12-02** * Forms are now available via an include, you can use the *form* include on [Standing](/v3/endpoints-and-entities/entities/standing-and-topscorer) entities to get the (historical) form of a participant per fixture. You can use the sort\_order field to display the form, the latest fixtures have the highest sort\_order. ### **2022-12-01** * An [endpoint](/v3/core-api/endpoints/filters/get-all-entity-filters) to keep track of the available filters per entity has been implemented. ### **2022-11-28** * A dynamic filter for [Stages](/v3/endpoints-and-entities/endpoints/stages) has been added. It is available on every entity that has a relation to a stage, for example on a fixture, you can apply it like so *\&filters=fixtureStages:11* * We have implemented a *sidelined* include on [Fixture](/v3/endpoints-and-entities/entities/fixture) entities. It will return the sidelined players for the given fixture. * It is now possible to add the *filters=populate* to your query parameter. This parameter allows for a higher pagination limit (max 1000), so you can populate your database in a more convenient way instead of using the default pagination limit of 50. To prevent our services from being overloaded, using includes is disabled when this filter is added to the request. ### **2022-11-25** * Because of a typo, we have renamed the yersey\_number field in Lineup entities, to jersey\_number. ### **2022-11-22** * The *detailed\_position\_id* field has been removed from a Lineup entity. This field became obsolete, to build a (visual) formation you should use the formation\_field attribute which is also available on the Lineup entity. The *detailed\_position\_id* is still available on the Player entity, indicating the preferred position of the player / the position where the player plays the most, a players *detailed\_position\_id* may change over time. ### **2022-11-21** * When requesting a page that utilizes pagination, the *next\_page* attribute now contains the query parameters from the original request. This way you can easily propogate through the results with the same context like includes and filters. If you are using the API token as a query parameter for authentication, you still have to add this to your next request. ### **2022-11-15** * The 'value' field on Trend entities is now automatically casted to a float. ### **2022-11-04** * A filter called *deleted* has been implemented. The filter can be passed on [Fixtures](/v3/endpoints-and-entities/endpoints/fixtures) entities to only request fixtures that have a *is\_deleted* [State](/v3/endpoints-and-entities/endpoints/states). This is handy to keep your database in Sync with ours, since fixtures with a deleted state are excluded from default responses. * An endpoint to retrieve jerseys has been implemented. You can request the current seasons jerseys via league id. ### **2022-11-03** * The Aggregated Topscorers by Season Id endpoint has been removed. It became obsolete since we have now separated *Stage Topscorers* and *Season Topscorers*. Requesting [Season Topscorers](/v3/endpoints-and-entities/endpoints/topscorers/get-topscorers-by-season-id) now returns the same result as an "aggregated" call would return beforehand. * We have added a *formations* include, which is now available under the [Fixture](/v3/endpoints-and-entities/endpoints/fixtures) entity. This provides a more convenient to request the formations for the given fixtures participants. In before implementing this include, it was available as a value when requesting the *metadata* include. Requesting formations via the metadata is now deprecated and will be removed before API V3 will go out of Beta. * We have added a *ballCoordinates* include, which is now available under the [Fixture](/v3/endpoints-and-entities/endpoints/fixtures) entity. This provides a more convenient to request ball coordinates for the given fixture. In before implementing this include, it was available as a value when requesting the *metadata* include. Requesting ball coordinates via the metadata is now deprecated and will be removed before API V3 will go out of Beta. ### **2022-11-01** * From now on, when requests return no results, an extra field *message* will be added to the response, stating no results were returned. This can either be due to the query not returning any (more) results, or because the subscription not allowing access to the requested data. ### **2022-10-26** * A new pagination system has been implemented. From now on, we will no longer provide a `count` and `total_pages` property in the meta of the response. Instead, you can paginate using the `has_more` parameter to determine if you can still propagate through results. This change decreases the load on our databases and massively increases API response speed and reliability. * A new filter called `idAfter` has been implemented on endpoints returning all entities, for example the [All Leagues endpoint ](/v3/endpoints-and-entities/endpoints/leagues/get-all-leagues)or [All Fixtures endpoint.](/v3/endpoints-and-entities/endpoints/fixtures/get-all-fixtures) This is especially useful for pagination, e.g to easily determine which entities have been newly created in our databases compared to yours. You can use it like so: {% code overflow="wrap" %} ```javascript https://api.sportmonks.com/v3/football/leagues?api_token={your_token}&filters=idAfter:2000 ``` {% endcode %} This will only return leagues with an ID higher than 2000. ### **2022-10-25** * We have changed the URL of the endpoint that returns the latest updated fixtures. In before this change, it was available via *fixtures/updates*. To better follow naming conventions of similar endpoints in our API, it is now accessible via [*fixtures/latest*](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/fixtures/get-latest-updated-fixtures). * The parameter for the [fixtures/latest](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/fixtures/get-latest-updated-fixtures) endpoint has changed. It will now return fixtures that have been updated in the last *5 minutes*. # Syntax > This syntax applies broadly across most Sportmonks endpoints. Each endpoint’s documentation will point out any exceptions. ### Syntax operators & usage | Operator | Purpose | Example | | ----------- | ------------------------------------------------ | ------------------------------------ | | `&select=` | Pick specific fields on the base entity | `&select=name,starting_at` | | `&include=` | Include related entities / relations | `&include=lineups,events` | | `;` | Terminates one include chain and allows new ones | `&include=lineups;events` | | `:` | Indicates field selection inside an include | `&include=events:player_name,minute` | | `,` | Separates multiple IDs or fields | `&filters=eventTypes:14,18` | ### Example use patterns **Base field selection** Fetch only fields you need: ``` ?api_token=…&select=name,starting_at ``` **Including relations** Include related data objects: ``` ?api_token=…&include=lineups,events ``` **Field filtering inside includes** Limit fields of included relations: ``` ?api_token=…&include=events:player_name,minute&filters=eventTypes:14,18 ``` **Nested includes (multi-level)** Chain includes for nested relations: ``` ?api_token=…&include=events.player.country:name ``` ### Exceptions & endpoint-specific notes > ⚠️ Some endpoints do **not** support certain operators or include relations. Always review the endpoint’s documentation for allowed fields and relations. * Invalid syntax (wrong field names, relations, or separators) may cause a **400 Bad Request**. * When using both `include` and `filters`, filters may apply to the base entity or included entities depending on endpoint behavior. * Some endpoints restrict depth of includes or fields allowed — use the “Allowed includes / fields” section of that endpoint page.

Syntax	Usage	Example
`&select=`	Select specific fields on the base entity	`&select=name`
`&include=`	Include relations	`&include=lineups`
`&filters=`	Filter your request	`&filters=eventTypes:15`
`;`	Mark end of (nested) relation. You can start including other relations from here	`&include=lineups;events;participants`
`:`	Mark field selection	`&include=lineups:player_name;events:player_name,related_player_name,minute`
`,`	Used as separation to select or filter on more IDs	`&include=events:player_name,related_player_name,minute&filters=eventTypes:15`

# Request options This chapter shows you how to fine-tune your API calls using **includes**, **selecting fields**, using **filtering**, and **ordering / sorting**. Mastering request options helps you fetch exactly what you need and omit what you don’t for faster, leaner, more efficient responses. {% content-ref url="/pages/8woqlNbvAd1VURLluxzr" %} [Includes](/v3/api/request-options/includes) {% endcontent-ref %} {% content-ref url="/pages/Xxrws6kugi3UtJ8ZiPrU" %} [Selecting fields](/v3/tutorials-and-guides/tutorials/filter-and-select-fields/selecting-fields) {% endcontent-ref %} {% content-ref url="/pages/eF1NC9L4erLtB2KLQoSM" %} [Filtering](/v3/api/request-options/filtering) {% endcontent-ref %} {% content-ref url="/pages/O3JMbzOjrYz4Xj4xGKWP" %} [Selecting and filtering](/v3/api/request-options/selecting-and-filtering) {% endcontent-ref %} {% content-ref url="/pages/8cSk6PiDzZuXbCgh8pnv" %} [Ordering and sorting](/v3/api/request-options/ordering-and-sorting) {% endcontent-ref %} # Includes The `includes` parameter in the Sportmonks Football API allows you to enrich your API responses by including related resources in a single request. By using includes, you can avoid making multiple API calls to gather related data, making your integrations more efficient and performant. ### Overview When querying an endpoint, you can include additional related data by specifying the `include` parameter in your request. This allows you to receive related entities, such as team details, player statistics, and more, all within the same response. The available includes depend on the specific endpoint you're accessing.

Parameter	Required	Description
`include`	No	Enrich the API response with more data by using includes.

### Example Let's say you want to retrieve fixture alongside with the associated teams for that fixture. You can do this by adding the `include` parameter to your request: {% tabs %} {% tab title="Request" %} ``` https://api.sportmonks.com/v3/football/fixtures/{ID}&include=participants ``` {% endtab %} {% tab title="Response" %} ``` { "data": { "id": 19032598, "sport_id": 1, "league_id": 1326, "season_id": 22842, "stage_id": 77468270, "group_id": null, "aggregate_id": null, "round_id": null, "state_id": 5, "venue_id": 1944, "name": "Spain vs England", "starting_at": "2024-07-14 19:00:00", "result_info": "Spain won after full-time.", "leg": "1/1", "details": "Match 51", "length": 90, "placeholder": false, "has_odds": true, "has_premium_odds": true, "starting_at_timestamp": 1720983600, "participants": [ { "id": 18645, "sport_id": 1, "country_id": 462, "venue_id": 1315, "gender": "male", "name": "England", "short_code": "ENG", "image_path": "https://cdn.sportmonks.com/images/soccer/teams/21/18645.png", "founded": 1863, "type": "national", "placeholder": false, "last_played_at": "2024-07-14 19:00:00", "meta": { "location": "away", "winner": false, "position": 2 } }, { "id": 18710, "sport_id": 1, "country_id": 32, "venue_id": 2020, "gender": "male", "name": "Spain", "short_code": "ESP", "image_path": "https://cdn.sportmonks.com/images/soccer/teams/22/18710.png", "founded": 1913, "type": "national", "placeholder": false, "last_played_at": "2024-07-14 19:00:00", "meta": { "location": "home", "winner": true, "position": 1 } } ] }, ``` {% endtab %} {% endtabs %} ### Nested Includes Some includes allow you to drill down even further into related data by using nested includes.You can read more on that on this page: {% content-ref url="/pages/2m6obvxTccNxE5VC0zWS" %} [Nested includes](/v3/api/request-options/includes/nested-includes) {% endcontent-ref %} # Nested includes The nested include allows you to further enrich your data by requesting more information from a standard include. Might sound difficult, but we assure you, it’s anything but hard. This is how we use nested includes. ### Create your request For example, in our [includes tutorial ](/v3/tutorials-and-guides/tutorials/includes)you’ve enriched your [GET Fixture by Date](/v3/endpoints-and-entities/endpoints/fixtures/get-fixtures-by-date) request with the `participant`, and `events` includes: ```javascript https://api.sportmonks.com/v3/football/fixtures/date/2022-09-03?api_token=YOUR_TOKEN&include=participants;events ``` The include event shows you the data about players who received a card, scored a goal, or were substituted. A snippet of the response:

Response

```javascript { "data": [ { "id": 18535517, "sport_id": 1, "league_id": 501, "season_id": 19735, "stage_id": 77457866, "group_id": null, "aggregate_id": null, "round_id": 274719, "state_id": 5, "venue_id": 8909, "name": "Celtic vs Rangers", "starting_at": "2022-09-03 11:30:00", "result_info": "Celtic won after full-time.", "leg": "1/1", "details": null, "length": 90, "placeholder": false, "last_processed_at": "2023-02-17 10:19:55", "has_odds": true, "starting_at_timestamp": 1662204600, "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": "home", "winner": true, "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": "away", "winner": false, "position": 2 } } ], "events": [ { "id": 42683644, "fixture_id": 18535517, "period_id": 4296154, "participant_id": 53, "type_id": 18, "section": "event", "player_id": 3298, "related_player_id": 10966261, "player_name": "Aaron Mooy", "related_player_name": "R. Hatate", "result": null, "info": null, "addition": null, "minute": 73, "extra_minute": null, "injured": false, "on_bench": false, "coach_id": null, "sub_type_id": null }, //And more ```

But what if we want to know more about the players, who scored a goal, like their country of origin, height, weight, age, image, etc? This is where the nested include comes into play! ### Using nested includes The nested includes are represented in the form of dots (.), which are then linked to a standard include. This shows their relationship. {% hint style="info" %} Check our [syntax section](/v3/api/syntax) for a complete syntax overview. {% endhint %} Because the include event is related to a player. You can add `.player` to the include, which will result in the nested include: `events.player` {% code overflow="wrap" %} ```javascript https://api.sportmonks.com/v3/football/fixtures/date/2022-09-03?api_token=YOUR_TOKEN&include=participants;events.player ``` {% endcode %}

Response

# Selecting fields ## Field selection API 3.0 introduces the possibility to request specific fields on entities. This possibility comes in handy when you only use particular fields in an API response. The advantage of selecting specific fields is that it reduces the response speed in mainly large responses. In addition to reducing response time, the response size can also be drastically reduced. Let's take a look together at an example. ### Only select a specific field One of our new additions to API 3.0 is a name field on the fixtures. The name field contains a textual representation of the participants playing the fixture. Without selecting a specific field, the API request and response would look like this: ```javascript https://api.sportmonks.com/v3/football/fixtures/18535517?api_token=YOUR_TOKEN ```

Response

As you can see in the example response above, the 'name' field is only returned for the fixture. {% hint style="info" %} Please note that the fields that have relations are also automatically included for technical reasons. {% endhint %} ### Select a specific field on an include You can also use field selection based on includes. Imagine you want to access fixture lineup information from Celtic vs Ranger (fixture id: 18535517). Additional to the lineups, you also wish to receive the display names, player images and country details. {% hint style="warning" %} Please note that we only copied the first player in the lineup in the below examples {% endhint %} Without selecting specific fields, you will receive a lot of information you don't need. The API request and partial API response would look like this: {% code overflow="wrap" %} ```javascript https://api.sportmonks.com/v3/football/fixtures/18535517?api_token=YOUR_TOKEN&include=lineups.player;lineups.player.country ``` {% endcode %}

Response

Now, let's select specific fields on the base entities used. Since we're using the `lineups.player` include, the first base entity is [players](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#players). We can select on all the fields of that entity. In our example, you need to select `display_name` and `image_path.` The second base entity is [countries](https://docs.sportmonks.com/v3/core-api/). Just like on the player entity, we can select on all the fields of the [countries](https://docs.sportmonks.com/v3/core-api/) entity. In our example, you need to select `name` and `image_path.` The new API request and partial API response would look like this: {% code overflow="wrap" %} ```javascript https://api.sportmonks.com/v3/football/fixtures/18535517?api_token=YOUR_TOKEN&include=lineups.player:display_name,image_path;lineups.player.country:name,image_path ``` {% endcode %}

Response

See how the size of the response is reduced? Next to selecting specific fields on the base entity or includes, it’s possible to filter your request. Check the next section for more info. # Filtering ## Filter your request ### Filter on includes Next to selecting specific fields on the base entity or includes, it’s possible to filter your request. Filters are improved in API 3 to give even more possibilities to get the data the way you need it. Each endpoint has two types of filters, static and dynamic filters. You can combine any dynamic filter with any static filter or use a multitude. **Static filters** are always the same and filter in one specific way without any custom options. The **dynamic filters** are based on entities and includes. Each dynamic filter uses an entity to filter on and one entity to apply the filter to. Below is an example with an explanation of how filters are set up. {% hint style="info" %} {% endhint %}

1. The include or base Entity you want to filter, this entity defines what you are filtering and what results are modified. In this case, you want to filter statistics. This is always a **singular** version of the entity. 2. The Entities you expect to receive when filtering. In this case, you want to receive all the statistics that have a specific type. This is always a **plural** version of the entity. 3. The ID's you want to filter on for the 2nd part, in this case types. You can separate the ID's by using a comma. **You can find more information in our Filtering Tutorial:** {% content-ref url="/pages/XhTQVBILLc6E4xkQ9qSK" %} [Filtering](/v3/tutorials-and-guides/tutorials/filter-and-select-fields/filtering) {% endcontent-ref %} # Selecting and filtering Thanks to the API flexibility, you can select specific fields and filter simultaneously! Let’s continue with our events example from the last section: we want all the goal and substitution events: {% code overflow="wrap" %} ```javascript https://api.sportmonks.com/v3/football/fixtures/18535517?api_token=YOUR_TOKEN&include=events.type&filters=eventTypes:18,14 ``` {% endcode %} {% hint style="info" %} This time we’ve used the include events.type to have the name of the event type included in the response. More information about this can be found in our [nested include tutorial.](/v3/tutorials-and-guides/tutorials/enrich-your-response/nested-includes) {% endhint %} Now, the events include contains a lot of information we’re not interested in. Frankly, we’re only interested in the name of the players related to the event and the minute the event occurred. As you’ve learnt, we can select all the fields on the base entity. In our example, the events entity. We need the `player_name,` `related_player_name` and `minute` field. This results in the following steps: 1. Add the include: `&include=events` 2. Determine the fields you’re interested in: `“player_name”,` `“related_player_name”` and `“minute”` field. 3. Select the fields: `&include=events:player_name,related_player_name,minute` The above steps result in the following request: {% code overflow="wrap" %} ```javascript https://api.sportmonks.com/v3/football/fixtures/18535517?api_token=YOUR_TOKEN&include=events:player_name,related_player_name,minute ``` {% endcode %} Now, add the filter from the previous filter request: `&filters=eventTypes:18,14` {% code overflow="wrap" %} ```javascript https://api.sportmonks.com/v3/football/fixtures/18535517?api_token=YOUR_TOKEN&include=events:player_name,related_player_name,minute&filters=eventTypes:18,14 ``` {% endcode %}

Response

{% hint style="info" %} Please note that if you also want the name of the event type you need to add the `events.type` include as well. `https://api.sportmonks.com/v3/football/fixtures/18535517?api_token=YOUR_TOKEN&include=events:player_name,related_player_name,minute;event.type&filters=eventTypes:18,14` {% endhint %} # Ordering and sorting For paginated endpoints, the API supports ordering on a specific field. Read more on how to use ordering on this page. {% hint style="info" %} We would love your feedback on the sorting functionality! If you have suggestions for fields to apply sorting on, or have encountered any issues, please contact {% endhint %} ## Ordering The `order` query parameter is used to specify the order in which paginated results should be returned. By default, results are returned in ascending order. However, you can use the `order` parameter to specify that results should be returned in descending order instead. Using ordering allows for more convenient results to be returned, next to that it can potentially save you from making API calls as you don't have to propagate through redundant results. ### **Parameters** | Parameter | Required | Description | | --------- | -------- | ---------------------------------------------------------------- | | `order` | No | The order in which results should be returned (`asc` or `desc`). | ### **Usage** To use the `order` query parameter, simply include it in the request URL for paginated endpoints. For example: ```url https://api.sportmonks.com/v3/football/fixtures?api_token=YOUR_TOKEN&page=2&order=desc ``` In this example, the API will return page 2 of results for the `leagues` endpoint, in descending order. {% hint style="info" %} The field used for ordering differs per endpoint, you should consult the endpoints documentation page to see what field the ordering applies on. {% endhint %} ## Custom sorting You can use custom sorts on endpoints; this enables the sorting of base entities returned in the endpoint responses. This feature is designed to enhance flexibility and customisation for users interacting with the API. ### Usage This provides users with the ability to customise sorting of returned data through the use of the `sortBy` and `order` parameters. This functionality is particularly useful when retrieving lists of fixtures in football, as it allows users to organise the data based on specific criteria. **Sorting Fixtures** When querying fixtures, users can specify the field to sort by and the desired order using the following parameters: * **sortBy**: Specifies the field by which the data will be sorted. Currently supported fields include `starting_at` and `name`. * **order**: Determines the order in which the data will be sorted. Users can choose between ascending (`asc`) and descending (`desc`) orders. ### Examples **Sort by `starting_at`**: This option sorts the fixtures based on their starting date and time. ```bash https://api.sportmonks.com/v3/football/fixtures&sortBy=starting_at&order=desc ``` This URL sorts the fixtures in descending order of their starting date and time. **Sort by `name`**: This option sorts the fixtures alphabetically based on their names. ```bash https://api.sportmonks.com/v3/football/fixtures&sortBy=name&order=asc ``` This URL sorts the fixtures alphabetically by their names in ascending order. {% hint style="info" %} Sorting on the `name` field currently works for all entities with a `"name"` field. For Fixtures, sorting also works on the `starting_at` field. {% endhint %} {% hint style="danger" %} If an unsupported field is passed to sort on, an error is thrown, and the request returns a 400 Bad Request HTTP code. {% endhint %} We want to encourage users to provide feedback on the sorting functionality. If you have suggestions for new fields or have encountered any issues, please contact to improve and enhance the API experience. Feel free to reach out with any questions or suggestions! # Rate limit Your rate limit defines how many API calls you can make per entity per hour, based on your active plan and any API call add-ons you’ve purchased. #### Rate limits per plan Each plan includes a fixed number of API calls per entity per hour: * **Starter**: 2,000 API calls / entity / hour * **Growth:** 2,500 API calls / entity / hour * **Pro**: 3,000 API calls / entity / hour * **Enterprise**: 5,000 API calls / entity / hour If you’ve purchased API call add-ons, these increase your hourly limit accordingly. Understanding and optimising your API usage is critical for building reliable applications. This guide explains how rate limits work, how to stay within them, and strategies for maximum efficiency. ### Quick summary **Default limits:** * Limits are per entity, not per endpoint * Resets after 1 hour from first request * Track usage in real-time via response headers **When you hit the limit:** * You receive a `429 Too Many Requests` error * You can still call other entities * Wait for reset or upgrade your plan **Pro tip:** Use includes, cache reference data, and implement smart polling to reduce API calls by 50-80%. ### 1. How rate limits work **Key points:** * ✅ Limits are **per entity** (Fixture, Team, Player, etc.) * ✅ The hour starts from your **first request** to that entity * ✅ After 1 hour from the first request, your limit **resets** * ✅ Different entities have **separate limits** #### Example timeline ``` 18:18 UTC - First Fixture request → Counter starts at 2,999 remaining 18:30 UTC - 50 more Fixture requests → 2,949 remaining 19:00 UTC - 200 more Fixture requests → 2,749 remaining 19:18 UTC - Limit resets to 3,000 → Full limit restored ``` #### What counts as a request? **Each of these counts as ONE request:** * `GET /fixtures/123` * `GET /fixtures?date=2026-03-02` * `GET /fixtures/123?include=participants;events;statistics` * Each page in paginated results **These count as SEPARATE requests:** * `GET /fixtures/123` (1 Fixture request) * `GET /teams/456` (1 Team request) * Different entities = different rate limit buckets ### 2. Understanding entities vs endpoints {#entities-vs-endpoints} This is crucial: **Rate limits are per entity, not per endpoint.** #### Entity examples | Entity | Endpoints That Use This Entity | | ----------- | --------------------------------------------------------------------- | | **Fixture** | `/fixtures`, `/fixtures/{id}`, `/fixtures/date/{date}`, `/livescores` | | **Team** | `/teams`, `/teams/{id}`, `/teams/search/{name}` | | **Player** | `/players`, `/players/{id}`, `/players/search/{name}` | | **League** | `/leagues`, `/leagues/{id}`, `/leagues/search/{name}` | | **Season** | `/seasons`, `/seasons/{id}`, `/seasons/search/{name}` | #### Example Scenario ```javascript // These ALL count toward the SAME Fixture entity limit await fetch('/fixtures/123'); // Fixture request #1 await fetch('/fixtures/date/2026-03-02'); // Fixture request #2 await fetch('/fixtures/multi/123,456,789'); // Fixture request #3 await fetch('/livescores/inplay'); // Fixture request #4 (livescores use Fixture entity) // Current Fixture limit usage: 4/3000 // This uses a DIFFERENT limit (Team entity) await fetch('/teams/53'); // Team request #1 // Fixture: 4/3000, Team: 1/3000 ``` #### Why this matters On the Growth Plan could theoretically make: * 3,000 Fixture requests * 3,000 Team requests * 3,000 Player requests * 3,000 League requests **= 12,000+ total requests per hour** (if you use multiple entities) ### 3. Monitoring your usage #### Check response headers Every successful API response includes a `rate_limit` object: ```json { "data": { ... }, "rate_limit": { "resets_in_seconds": 1847, "remaining": 2749, "requested_entity": "Fixture" } } ``` **Fields explained:** * `resets_in_seconds` - Time until limit resets (in seconds) * `remaining` - Requests left for this entity * `requested_entity` - Which entity this applies to #### Track in your code ```javascript async function makeRequest(url) { const response = await fetch(url); const data = await response.json(); // Log usage const { remaining, resets_in_seconds, requested_entity } = data.rate_limit; console.log(`${requested_entity}: ${remaining} requests remaining`); console.log(`Resets in: ${Math.floor(resets_in_seconds / 60)} minutes`); // Warn when low if (remaining < 100) { console.warn(`⚠️ Low on ${requested_entity} requests! Optimise your calls.`); } return data; } ``` #### Usage dashboard Check real-time usage at: * **MySportmonks dashboard:** [my.sportmonks.com](https://my.sportmonks.com/) * **API endpoint:** `GET /core/my/usage` - Programmatic usage data **Example response:** ```json { "data": [ { "entity": "Fixture", "requests_made": 251, "remaining_requests": 2749, "period_start": "2026-03-02 18:18:00", "period_end": "2026-03-02 19:18:00" }, { "entity": "Team", "requests_made": 45, "remaining_requests": 2955, "period_start": "2026-03-02 18:25:00", "period_end": "2026-03-02 19:25:00" } ] } ``` ### 4. Optimisation strategies #### Strategy 1: Use includes **The problem:** ```javascript // ❌ Bad: 3 separate requests const fixture = await fetch('/fixtures/123'); const homeTeam = await fetch('/teams/53'); const awayTeam = await fetch('/teams/62'); // = 1 Fixture + 2 Team requests ``` **The Solution:** ```javascript // ✅ Good: 1 request with includes const fixture = await fetch('/fixtures/123?include=participants'); // = 1 Fixture request (teams included in response) ``` **Impact:** Reduced from 3 requests to 1 = **67% savings** #### Strategy 2: Cache reference data **Reference data changes rarely - cache it!** **What to cache:** * Types (statistics types, event types, etc.) * States (fixture states) * Leagues (your available leagues) * Venues (stadium information) * Markets & Bookmakers (if using odds) **How long to cache:** * Types & States: **1 week** (rarely change) * Leagues: **1 day** (occasionally update) * Venues: **1 week** (stable data) * Teams/Players: **1 hour** (injuries/transfers happen) **Example implementation:** ```javascript class CachedAPI { constructor(apiToken) { this.token = apiToken; this.cache = new Map(); } async getTypes() { const cacheKey = 'types'; const cacheTime = 7 * 24 * 60 * 60 * 1000; // 1 week if (this.cache.has(cacheKey)) { const { data, timestamp } = this.cache.get(cacheKey); if (Date.now() - timestamp < cacheTime) { console.log('✅ Using cached types'); return data; } } console.log('📡 Fetching fresh types'); const response = await fetch(`/core/types?api_token=${this.token}`); const data = await response.json(); this.cache.set(cacheKey, { data: data.data, timestamp: Date.now() }); return data.data; } // Create a quick lookup map async getTypeById(typeId) { const types = await this.getTypes(); return types.find(t => t.id === typeId); } } // Usage const api = new CachedAPI('YOUR_TOKEN'); // First call - fetches from API const type1 = await api.getTypeById(86); // "Shots On Target" // Next 1000 lookups - all from cache (0 API calls!) const type2 = await api.getTypeById(52); // "Goals" const type3 = await api.getTypeById(78); // "Tackles" ``` **Impact:** Instead of 1000+ Type requests, you make 1 = **99.9% savings** #### Strategy 3: Batch operations **Use Multi-ID endpoints:** ```javascript // ❌ Bad: 10 separate requests for (const id of [123, 456, 789, 101, 102, 103, 104, 105, 106, 107]) { await fetch(`/fixtures/${id}`); } // = 10 Fixture requests // ✅ Good: 1 batched request const ids = [123, 456, 789, 101, 102, 103, 104, 105, 106, 107]; await fetch(`/fixtures/multi/${ids.join(',')}`); // = 1 Fixture request ``` **Impact:** Reduced from 10 requests to 1 = **90% savings** #### Strategy 4: Smart polling for livescores **Don't poll everything constantly:** ```javascript // ❌ Bad: Poll all matches every 5 seconds setInterval(async () => { await fetch('/livescores'); // Even pre-match and finished games! }, 5000); // ✅ Good: Poll only what's needed async function smartLivescorePolling() { // Get only matches that updated in last 10 seconds const updates = await fetch('/livescores/latest?api_token=YOUR_TOKEN'); // Only update UI for changed matches updateOnlyChangedMatches(updates.data); } // Poll every 10 seconds (not 5) setInterval(smartLivescorePolling, 10000); // Or even better - only poll during live matches function adaptivePolling() { const hasLiveMatches = checkIfAnyLiveMatches(); if (hasLiveMatches) { // Poll every 10 seconds during live matches return setInterval(smartLivescorePolling, 10000); } else { // Poll every 5 minutes when no live matches return setInterval(smartLivescorePolling, 300000); } } ``` **Impact:** Reduced polling frequency #### Strategy 5: Pagination optimisation **Use `filters=populate` for database population:** ```javascript // ❌ Slow: Many requests with includes disabled // Default: 25 per page = 40 requests for 1000 items for (let page = 1; page <= 40; page++) { await fetch(`/fixtures?page=${page}`); } // ✅ Fast: Fewer requests, more items per page // With populate: 1000 per page = 1 request for 1000 items await fetch('/fixtures?filters=populate&per_page=1000'); // Note: includes are disabled with populate filter ``` **Impact:** Reduced from 40 requests to 1 = **97.5% savings** #### Summary: Combined impact **Before optimisation:** ``` Daily API Calls for a typical livescore app: - 10,000 fixture requests - 5,000 team requests - 3,000 type lookups - 2,000 state lookups = 20,000 total requests/day ``` **After Optimisation:** ``` Daily API Calls with all strategies: - 2,000 fixture requests (includes, batching, smart polling) - 500 team requests (includes) - 1 type lookup (cached for 1 week) - 1 state lookup (cached for 1 week) = 2,502 total requests/day ``` **Total Savings: 87.5%** 🎉 ### 5. Handling rate limit errors #### What happens when you hit the limit? **You receive a `429 Too Many Requests` response:** ```json { "error": "Too Many Requests", "message": "Rate limit of 3000 requests per hour exceeded.", "retry_after": 1847, "rate_limit": { "remaining": 0, "total": 3000, "resets_in_seconds": 1847, "requested_entity": "Fixture" } } ``` #### Implement retry logic ```javascript async function fetchWithRetry(url, maxRetries = 3) { for (let attempt = 0; attempt < maxRetries; attempt++) { try { const response = await fetch(url); if (response.status === 429) { const data = await response.json(); const retryAfter = data.retry_after || Math.pow(2, attempt) * 1000; console.log(`Rate limited. Retrying after ${retryAfter}ms...`); await sleep(retryAfter); continue; } return response; } catch (error) { if (attempt === maxRetries - 1) throw error; await sleep(Math.pow(2, attempt) * 1000); } } } function sleep(ms) { return new Promise(resolve => setTimeout(resolve, ms)); } ``` #### Client-side rate limiting **Prevent hitting limits in the first place:** ```javascript class RateLimiter { constructor(maxRequests = 3000, windowMs = 3600000) { this.maxRequests = maxRequests; this.windowMs = windowMs; this.requests = new Map(); // entity -> [timestamps] } async throttle(entity = 'default') { const now = Date.now(); // Get request history for this entity if (!this.requests.has(entity)) { this.requests.set(entity, []); } const entityRequests = this.requests.get(entity); // Remove old requests outside the window const validRequests = entityRequests.filter( time => now - time < this.windowMs ); // Check if we're at the limit if (validRequests.length >= this.maxRequests) { const oldestRequest = validRequests[0]; const waitTime = this.windowMs - (now - oldestRequest); console.log(`Throttling ${entity}: waiting ${waitTime}ms`); await sleep(waitTime); // Recursively try again return this.throttle(entity); } // Add this request to history validRequests.push(now); this.requests.set(entity, validRequests); } } // Usage const limiter = new RateLimiter(3000, 3600000); // 3000/hour async function makeRequest(url, entity) { await limiter.throttle(entity); return fetch(url); } // These will be automatically throttled await makeRequest('/fixtures/123', 'Fixture'); await makeRequest('/teams/456', 'Team'); ``` ### 6. Code examples {% tabs %} {% tab title="JavaScript" %} ```js class SportmonksAPI { constructor(apiToken, options = {}) { this.token = apiToken; this.baseURL = 'https://api.sportmonks.com/v3/football'; this.cache = new Map(); this.rateLimiter = new RateLimiter( options.maxRequests || 2800, // Leave buffer options.windowMs || 3600000 ); } async request(endpoint, params = {}, entity = 'default') { // Throttle request await this.rateLimiter.throttle(entity); // Build URL const url = new URL(`${this.baseURL}${endpoint}`); url.searchParams.append('api_token', this.token); Object.entries(params).forEach(([key, value]) => { url.searchParams.append(key, value); }); // Make request with retry try { const response = await this.fetchWithRetry(url.toString()); const data = await response.json(); // Log rate limit info this.logRateLimit(data.rate_limit); return data; } catch (error) { console.error('API Error:', error); throw error; } } async fetchWithRetry(url, maxRetries = 3) { for (let i = 0; i < maxRetries; i++) { const response = await fetch(url); if (response.status === 429 && i < maxRetries - 1) { const data = await response.json(); const retryAfter = data.retry_after || Math.pow(2, i) * 1000; console.log(`Retry after ${retryAfter}ms`); await sleep(retryAfter); continue; } return response; } } logRateLimit(rateLimit) { if (!rateLimit) return; const { remaining, requested_entity } = rateLimit; console.log(`${requested_entity}: ${remaining} remaining`); if (remaining < 200) { console.warn(`⚠️ Low on ${requested_entity} requests!`); } } // Cached method for types async getTypes() { const cacheKey = 'types'; if (this.cache.has(cacheKey)) { const { data, timestamp } = this.cache.get(cacheKey); if (Date.now() - timestamp < 7 * 24 * 60 * 60 * 1000) { return data; } } const response = await this.request('/core/types', {}, 'Type'); this.cache.set(cacheKey, { data: response.data, timestamp: Date.now() }); return response.data; } } // Usage const api = new SportmonksAPI('YOUR_TOKEN'); // Automatically throttled and cached const fixtures = await api.request('/fixtures', { filters: 'fixtureLeagues:501', include: 'participants;scores;events' }, 'Fixture'); const types = await api.getTypes(); // Cached for 1 week ``` {% endtab %} {% tab title="Python" %} ```py import time import requests from datetime import datetime, timedelta from typing import Dict, List, Optional class RateLimiter: def __init__(self, max_requests: int = 3000, window_seconds: int = 3600): self.max_requests = max_requests self.window_seconds = window_seconds self.requests: Dict[str, List[float]] = {} def throttle(self, entity: str = 'default'): now = time.time() if entity not in self.requests: self.requests[entity] = [] # Remove old requests self.requests[entity] = [ req_time for req_time in self.requests[entity] if now - req_time < self.window_seconds ] # Check if at limit if len(self.requests[entity]) >= self.max_requests: oldest = self.requests[entity][0] wait_time = self.window_seconds - (now - oldest) print(f"Throttling {entity}: waiting {wait_time:.2f}s") time.sleep(wait_time) return self.throttle(entity) # Add this request self.requests[entity].append(now) class SportmonksAPI: def __init__(self, api_token: str): self.token = api_token self.base_url = 'https://api.sportmonks.com/v3/football' self.cache = {} self.limiter = RateLimiter(max_requests=2800) # Leave buffer def request(self, endpoint: str, params: Optional[Dict] = None, entity: str = 'default'): # Throttle self.limiter.throttle(entity) # Build request url = f"{self.base_url}{endpoint}" if params is None: params = {} params['api_token'] = self.token # Make request with retry for attempt in range(3): try: response = requests.get(url, params=params, timeout=30) if response.status_code == 429: retry_after = response.json().get('retry_after', 2 ** attempt) print(f"Rate limited. Retrying after {retry_after}s") time.sleep(retry_after) continue response.raise_for_status() data = response.json() # Log rate limit if 'rate_limit' in data: remaining = data['rate_limit']['remaining'] print(f"{entity}: {remaining} remaining") return data except requests.exceptions.RequestException as e: if attempt == 2: raise time.sleep(2 ** attempt) def get_types(self): cache_key = 'types' cache_duration = timedelta(weeks=1) if cache_key in self.cache: data, timestamp = self.cache[cache_key] if datetime.now() - timestamp < cache_duration: print("Using cached types") return data response = self.request('/core/types', entity='Type') self.cache[cache_key] = (response['data'], datetime.now()) return response['data'] # Usage api = SportmonksAPI('YOUR_TOKEN') fixtures = api.request('/fixtures', { 'filters': 'fixtureLeagues:501', 'include': 'participants;scores' }, 'Fixture') types = api.get_types() # Cached ``` {% endtab %} {% tab title="PHP" %} ```php maxRequests = $maxRequests; $this->windowSeconds = $windowSeconds; } public function throttle($entity = 'default') { $now = time(); // Initialise entity if needed if (!isset($this->requests[$entity])) { $this->requests[$entity] = []; } // Remove old requests outside the window $this->requests[$entity] = array_filter( $this->requests[$entity], function($timestamp) use ($now) { return ($now - $timestamp) < $this->windowSeconds; } ); // Check if at limit if (count($this->requests[$entity]) >= $this->maxRequests) { $oldestRequest = min($this->requests[$entity]); $waitTime = $this->windowSeconds - ($now - $oldestRequest); echo "Throttling {$entity}: waiting {$waitTime}s\n"; sleep($waitTime); // Try again recursively return $this->throttle($entity); } // Add this request to history $this->requests[$entity][] = $now; } } class SportmonksAPI { private $token; private $baseUrl = 'https://api.sportmonks.com/v3/football'; private $cache = []; private $limiter; public function __construct($apiToken, $maxRequests = 2800) { $this->token = $apiToken; $this->limiter = new RateLimiter($maxRequests); } public function request($endpoint, $params = [], $entity = 'default', $maxRetries = 3) { // Throttle request $this->limiter->throttle($entity); // Build URL $params['api_token'] = $this->token; $url = $this->baseUrl . $endpoint . '?' . http_build_query($params); // Make request with retry logic for ($attempt = 0; $attempt < $maxRetries; $attempt++) { try { $response = $this->fetchWithRetry($url, $attempt); $data = json_decode($response, true); // Log rate limit info if (isset($data['rate_limit'])) { $this->logRateLimit($data['rate_limit']); } return $data; } catch (Exception $e) { if ($attempt === $maxRetries - 1) { throw $e; } // Exponential backoff $waitTime = pow(2, $attempt); echo "Request failed. Retrying after {$waitTime}s...\n"; sleep($waitTime); } } } private function fetchWithRetry($url, $attempt) { $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_TIMEOUT, 30); $response = curl_exec($ch); $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); if ($httpCode === 429) { $data = json_decode($response, true); $retryAfter = $data['retry_after'] ?? pow(2, $attempt); echo "Rate limited. Retrying after {$retryAfter}s...\n"; sleep($retryAfter); // Retry recursively return $this->fetchWithRetry($url, $attempt); } if ($httpCode !== 200) { throw new Exception("HTTP {$httpCode}: {$response}"); } return $response; } private function logRateLimit($rateLimit) { $remaining = $rateLimit['remaining'] ?? '?'; $entity = $rateLimit['requested_entity'] ?? 'Unknown'; echo "{$entity}: {$remaining} requests remaining\n"; if ($remaining < 200) { echo "⚠️ Low on {$entity} requests! Optimize your calls.\n"; } } // Cached method for types public function getTypes() { $cacheKey = 'types'; $cacheDuration = 7 * 24 * 60 * 60; // 1 week if (isset($this->cache[$cacheKey])) { $cached = $this->cache[$cacheKey]; if (time() - $cached['timestamp'] < $cacheDuration) { echo "Using cached types\n"; return $cached['data']; } } echo "Fetching fresh types\n"; $response = $this->request('/core/types', [], 'Type'); $this->cache[$cacheKey] = [ 'data' => $response['data'], 'timestamp' => time() ]; return $response['data']; } // Helper method for batched requests public function getFixturesByIds($ids) { if (empty($ids)) { return []; } $idsString = implode(',', $ids); return $this->request("/fixtures/multi/{$idsString}", [], 'Fixture'); } } // Usage Example try { $api = new SportmonksAPI('YOUR_TOKEN_HERE'); // Single fixture with includes $fixture = $api->request('/fixtures/123', [ 'include' => 'participants;scores;events' ], 'Fixture'); echo "Fixture: {$fixture['data']['name']}\n"; // Batched request $multipleFixtures = $api->getFixturesByIds([123, 456, 789]); echo "Fetched " . count($multipleFixtures['data']) . " fixtures\n"; // Cached types (only fetches once) $types = $api->getTypes(); echo "Got " . count($types) . " types\n"; // Types from cache (0 API calls) $typesAgain = $api->getTypes(); } catch (Exception $e) { echo "Error: " . $e->getMessage() . "\n"; } ?> ``` {% endtab %} {% endtabs %} ### 7. Common scenarios #### Scenario 1: Building a livescore app **Challenge:** Need frequent updates without hitting limits **Solution:** ```javascript // Poll smartly - only active matches async function updateLivescores() { // Use /livescores/latest - only matches updated in last 10s const response = await api.request('/livescores/latest', { include: 'scores;events' }, 'Fixture'); // Only update changed matches updateChangedMatches(response.data); } // Adaptive polling let pollInterval = null; function startPolling() { const hasLiveMatches = checkLiveMatches(); const interval = hasLiveMatches ? 10000 : 60000; // 10s or 1min if (pollInterval) clearInterval(pollInterval); pollInterval = setInterval(updateLivescores, interval); } ``` **API Calls:** \~360/hour during live matches, \~60/hour otherwise #### Scenario 2: Populating database **Challenge:** Need to fetch thousands of fixtures **Solution:** ```javascript // Use filters=populate for bulk operations async function populateFixtures(seasonId) { let hasMore = true; let page = 1; while (hasMore) { const response = await api.request('/fixtures', { filters: `populate;fixtureSeason:${seasonId}`, per_page: 1000, page: page }, 'Fixture'); // Save to database await saveToDB(response.data); hasMore = response.pagination.has_more; page++; // Be nice - small delay between pages await sleep(100); } } ``` **API Calls:** \~2-5 requests for entire season (vs 100+ without populate) #### Scenario 3: Statistics dashboard **Challenge:** Need lots of statistics data **Solution:** ```javascript // Cache types once, use includes efficiently const types = await api.getTypes(); // Cached - 0 API calls after first const typesMap = new Map(types.map(t => [t.id, t])); // Get fixture with all stats in one call const fixture = await api.request('/fixtures/123', { include: 'statistics;participants;scores' }, 'Fixture'); // Decode types from cache (no API calls) fixture.statistics.forEach(stat => { stat.typeName = typesMap.get(stat.type_id).name; }); ``` **API Calls:** 1 for data + 1 for types (cached forever) ### Best practices summary #### DO * Use includes to combine data * Cache reference data (types, states, leagues) * Implement client-side rate limiting * Monitor your usage regularly * Use `filters=populate` for bulk operations * Handle 429 errors gracefully with retry logic * Poll intelligently (only what's needed, when needed) * Batch requests with multi-ID endpoints #### DON'T * Poll every endpoint every 5 seconds * Fetch types/states/leagues repeatedly * Make separate requests when includes work * Ignore rate limit warnings * Request more data than you need * Skip error handling ### Quick checklist Use this to optimise your implementation: ``` □ Using includes to combine related data □ Caching types, states, and leagues □ Implemented rate limit monitoring □ Handling 429 errors with retry logic □ Using /livescores/latest instead of /livescores □ Polling at reasonable intervals (10-30s, not 1s) □ Using filters=populate for database population □ Batching requests with multi-ID endpoints □ Logging rate limit info for debugging □ Have fallback for when limits are hit ``` ### See also * [Error Codes - 429 Too Many Requests](https://docs.sportmonks.com/v3/api/error-codes#429-too-many-requests) - Handle rate limit errors * [Includes Tutorial](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes) - Combine data efficiently * [Best Practices](https://docs.sportmonks.com/v3/welcome/best-practices) - General optimisation * [Pagination](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/introduction/pagination) - Use populate filter * [MySportmonks](https://my.sportmonks.com/) - Monitor usage **Need Help?** * 📧 Email: #### For Enterprise plans Enterprise plans include a temporary burst buffer on top of the standard hourly limit. * The buffer allows short-term spikes (for example, during match days or major tournaments). * Once the standard limit is reached: * Requests continue until the buffer threshold is exceeded. * After the buffer is exceeded: * Requests may be temporarily throttled * Notifications are sent * The account may be flagged for review # Meta description Every request has a meta description. Let's take a look at a quick example.

Response

```javascript "subscription": [ { "meta": { "current_timestamp": 1773237412, "next_billing_cycle": "2026-03-23T11:30:11 UTC" }, "plans": [ { "plan": "Euro Club Tournaments - Trialing until 2026-03-23 11:30:11", "sport": "Football", "category": "All-in" }, { "plan": "Starter", "sport": "Football", "category": "Advanced" } ], "add_ons": [], "widgets": [], "bundles": [] } ], "rate_limit": { "resets_in_seconds": 3600, "remaining": 2499, "requested_entity": "League" }, "timezone": "UTC" } ```

It's easy to stay on top of your subscription details. You can find out what plan(s), add-ons and widgets you have, and see the timezone you're using. You'll also know when your trial ends (if you have one) and when your subscription expires. Additionally, you can see information about your rate limit. This way, you have all the information you need to manage your subscription. In the *rate\_limit* object, the following information is available: * *requested\_entity:* The requested entity for the current request * *remaining:* The number of API calls remaining for the requested entity * *resets\_in\_seconds:* amount of seconds left before the rate limit resets for the requested entity {% hint style="info" %} Check how our rate limit works in our [rate limit section.](/v3/api/rate-limit) {% endhint %} # Error codes Whenever you receive an unexpected response or experience unexpected behavior, check the HTTP response code and use this guide to troubleshoot the issue. ### Quick reference | Code | Error | When It Happens | Quick Fix | | ----- | --------------------- | ------------------------------------- | ---------------------------------------- | | `200` | OK | Request succeeded | No action needed ✅ | | `400` | Bad Request | Malformed request, invalid parameters | Check request syntax and parameters | | `401` | Unauthorized | Missing or invalid API token | Verify your API token | | `403` | Forbidden | Accessing unauthorized resource | Check your plan access | | `404` | Not Found | Resource doesn't exist | Verify the ID or endpoint | | `429` | Too Many Requests | Rate limit exceeded | Reduce request frequency or upgrade plan | | `500` | Internal Server Error | Server-side issue | Contact support if persistent | {% hint style="info" %} 💡 **Pro tip:** Always implement proper error handling in your code to catch and handle these errors gracefully. {% endhint %} ### Detailed error explanations Click an error code below for detailed troubleshooting information: #### 200: OK ✅ **What it means:** Your request was successful and data has been returned. **Response structure:** ```json { "data": { ... }, "subscription": [ ... ], "rate_limit": { ... }, "timezone": "UTC" } ``` **Best practices:** * Always check that `data` field exists before processing * Store `rate_limit` information to monitor your usage * Handle empty data arrays appropriately 📖 **Learn more:** [Understanding API Responses](https://docs.sportmonks.com/v3/api/syntax) #### 400: Bad request ❌ **What it means:** There's a problem with how your request is formatted or the parameters you're using. **Common causes:** **1. Invalid query parameters** ```bash # ❌ Wrong GET /fixtures?invalid_param=123 # ✅ Correct GET /fixtures?api_token=YOUR_TOKEN&filters=fixtureLeagues:501 ``` **2. Malformed include syntax** ```bash # ❌ Wrong - space in include GET /fixtures/123?include=participants, events # ✅ Correct - no spaces GET /fixtures/123?include=participants;events ``` **3. Invalid filter syntax** ```bash # ❌ Wrong - incorrect format GET /fixtures?filters=league=501 # ✅ Correct - proper format GET /fixtures?filters=fixtureLeagues:501 ``` **4. Invalid timezone** ```bash # ❌ Wrong - invalid timezone GET /fixtures?timezone=NewYork # ✅ Correct - proper timezone format GET /fixtures?timezone=America/New_York ``` **Example error response:** ```json { "message": "The given data was invalid.", "errors": { "filters": [ "The filters format is invalid." ] } } ``` **How to fix:** 1. **Check parameter spelling** - Use exact names from documentation 2. **Verify filter syntax** - See [Filter Tutorial](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/filter-and-select-fields) 3. **Validate include format** - Use semicolons, no spaces 4. **Test with minimal parameters** - Remove optional params to isolate issue **Code example (Error handling):** ```javascript try { const response = await fetch(url); const data = await response.json(); if (response.status === 400) { console.error('Bad Request:', data.message); console.error('Errors:', data.errors); // Fix your request parameters } } catch (error) { console.error('Request failed:', error); } ``` 📖 **Related:** [Request Options](https://docs.sportmonks.com/v3/api/request-options) | [Filter Tutorial](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/filter-and-select-fields) #### 401: Unauthorized 🔒 **What it means:** Your API token is missing, invalid, or expired. **Common causes:** **1. Missing API token** ```bash # ❌ Wrong - no token GET https://api.sportmonks.com/v3/football/fixtures # ✅ Correct - token included GET https://api.sportmonks.com/v3/football/fixtures?api_token=YOUR_TOKEN ``` **2. Token typo or extra spaces** ```bash # ❌ Wrong - extra space ?api_token= YOUR_TOKEN # ✅ Correct - no spaces ?api_token=YOUR_TOKEN ``` **3. Using test token in production** ```bash # ❌ Wrong environment Production URL + Test Token = 401 Error # ✅ Correct - matching environment Production URL + Production Token ``` **4. Revoked or expired token** * Token was regenerated in MySportmonks * Token was manually revoked * Account subscription expired **Example error response:** ```json { "error": "Unauthenticated.", "message": "Please provide a valid API token" } ``` **How to fix:** 1. **Verify your token:** * Go to [MySportmonks Dashboard](https://my.sportmonks.com) * Navigate to API tokens section * Copy the correct token (don't type it manually) 2. **Test with cURL:** ```bash curl "https://api.sportmonks.com/v3/football/fixtures?api_token=YOUR_TOKEN" ``` 3. **Check token format in code:** ```javascript // ✅ Correct implementation const API_TOKEN = process.env.SPORTMONKS_TOKEN; // From environment variable const url = `https://api.sportmonks.com/v3/football/fixtures?api_token=${API_TOKEN}`; ``` 4. **Common mistakes to avoid:** * ❌ Hardcoding tokens in frontend code (security risk) * ❌ Including quotes around the token * ❌ Adding spaces before or after the token * ❌ Using header authentication (use query parameter instead) **Security best practices:** ```javascript // ✅ Good - Server-side only // backend/api.js const SPORTMONKS_TOKEN = process.env.SPORTMONKS_TOKEN; // ❌ Bad - Exposed in frontend // frontend/app.js const SPORTMONKS_TOKEN = 'abcd1234...'; // Visible to users! ``` 📖 **Related:** [Authentication Guide](https://docs.sportmonks.com/v3/welcome/authentication) | [Best Practices](https://docs.sportmonks.com/v3/welcome/best-practices) #### 403: Forbidden 🚫 **What it means:** Your API token is valid, but you don't have permission to access this resource. **Common Causes:** **1. Resource not in your plan** ```bash # Your plan: Free Plan (Danish & Scottish leagues only) GET /fixtures?filters=fixtureLeagues:8 # Premier League # Result: 403 Forbidden ``` **2. Feature not available in your tier** ```bash # Your plan: Basic (no xG access) GET /fixtures/123?include=xGFixture # Result: 403 Forbidden ``` **3. Accessing premium endpoints** ```bash # Predictions endpoint requires add-on GET /predictions/probabilities/fixtures/123 # Result: 403 if you don't have Predictions add-on ``` **Example Error Response:** ```json { "error": "Access Denied", "message": "This resource is not available in your current subscription.", "resource": "xGFixture", "plan_required": "Standard or higher" } ``` **How to fix:** 1. **Check your plan access:** * Go to [MySportmonks Dashboard](https://my.sportmonks.com) * Review "My Subscriptions" section * Check which leagues and features are included 2. **Verify resource availability:** ```javascript // Check if resource is accessible try { const response = await fetch(url); if (response.status === 403) { console.log('Resource not available in your plan'); console.log('Upgrade at: https://www.sportmonks.com/football-api/#plans-pricing'); } } catch (error) { console.error(error); } ``` 3. **Common 403 scenarios:** | Scenario | Plan needed | Solution | | --------------------- | ------------------ | --------------------------------- | | Access Premier League | Standard+ | Upgrade or filter to your leagues | | Use xG data | Standard+ | Upgrade or remove xG includes | | Access Predictions | Predictions add-on | Add predictions to your plan | | Live odds | Odds package | Subscribe to odds package | 4. **Workarounds (if you can't upgrade):** * Filter requests to only leagues in your plan * Remove premium includes from requests * Check [Data Features by League](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/data-features-per-league) 📖 **Related:** [Plan Features](https://www.sportmonks.com/football-api/#plans-pricing) | [Data Features per League](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/data-features-per-league) #### 404: Not found 🔍 **What it means:** The resource you're trying to access doesn't exist. **Common Causes:** **1. Invalid ID** ```bash # ❌ Wrong - fixture doesn't exist GET /fixtures/99999999999 # ✅ Correct - use valid fixture ID GET /fixtures/18535517 ``` **2. Wrong endpoint path** ```bash # ❌ Wrong - typo in endpoint GET /v3/football/fixture/123 # "fixture" should be "fixtures" # ✅ Correct - proper endpoint GET /v3/football/fixtures/123 ``` **3. Resource was deleted** ```bash # Fixture was removed from database # (e.g., cancelled match, placeholder fixture) GET /fixtures/12345 # Result: 404 Not Found ``` **Example error response:** ```json { "error": "Not Found", "message": "The requested resource could not be found.", "resource_type": "fixture", "resource_id": "99999999" } ``` **How to fix:** 1. **Verify the ID exists:** ```javascript // Search for the resource first const searchResponse = await fetch( 'https://api.sportmonks.com/v3/football/fixtures/search/Celtic?api_token=YOUR_TOKEN' ); const results = await searchResponse.json(); // Then use a valid ID from results const fixtureId = results.data[0].id; ``` 2. **Check endpoint spelling:** ```javascript // ✅ Correct endpoints /v3/football/fixtures/{id} /v3/football/teams/{id} /v3/football/players/{id} /v3/football/leagues/{id} // ❌ Common mistakes /v3/football/fixture/{id} // Missing 's' /v3/soccer/fixtures/{id} // Wrong sport name /v3/football/match/{id} // Wrong entity name ``` 3. **Handle 404 gracefully:** ```javascript async function getFixture(fixtureId) { try { const response = await fetch( `https://api.sportmonks.com/v3/football/fixtures/${fixtureId}?api_token=YOUR_TOKEN` ); if (response.status === 404) { console.log('Fixture not found'); return null; // Return null instead of throwing error } return await response.json(); } catch (error) { console.error('Request failed:', error); throw error; } } ``` 4. **Use ID finder tool:** * Visit [ID Finder](https://my.sportmonks.com/resources/id-finder) * Search for teams, players, leagues, etc. * Get valid IDs for your requests 📖 **Related:** [API Structure](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/api-structure-and-navigation) | [Endpoints Reference](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints) #### 429: Too many requests ⏱️ **What it means:** You've exceeded your plan's rate limit. **Common causes:** **1. Making requests too quickly** ```javascript // ❌ Wrong - rapid fire requests for (let i = 0; i < 1000; i++) { fetch(url); // Hitting rate limit! } // ✅ Correct - with delay for (let i = 0; i < 1000; i++) { await fetch(url); await sleep(100); // 100ms delay } ``` **2. Inefficient API usage** ```javascript // ❌ Wrong - separate requests const team1 = await fetch('/teams/53'); const team2 = await fetch('/teams/62'); const fixture = await fetch('/fixtures/123'); // 3 API calls // ✅ Correct - use includes const fixture = await fetch('/fixtures/123?include=participants'); // 1 API call with all data ``` **3. Not caching reference data** ```javascript // ❌ Wrong - fetching types every time for (const stat of statistics) { const type = await fetch(`/types/${stat.type_id}`); // Wasteful! } // ✅ Correct - fetch once and cache const allTypes = await fetch('/types'); const typesMap = new Map(allTypes.data.map(t => [t.id, t])); // Use cached types for lookups ``` **Example error response:** ```json { "error": "Too Many Requests", "message": "Rate limit of 3000 requests per hour exceeded.", "retry_after": 1847, "rate_limit": { "remaining": 0, "total": 3000, "resets_in": "30:47" } } ``` **How to fix:** **1. Check your rate limit:** Every successful response includes rate limit info: ```json { "data": { ... }, "rate_limit": { "resets_in_seconds": 1847, "remaining": 2847, "requested_entity": "Fixture" } } ``` **2. Implement rate limiting:** ```javascript class RateLimiter { constructor(maxRequests, perSeconds) { this.maxRequests = maxRequests; this.perSeconds = perSeconds; this.requests = []; } async throttle() { const now = Date.now(); this.requests = this.requests.filter(time => now - time < this.perSeconds * 1000); if (this.requests.length >= this.maxRequests) { const oldestRequest = this.requests[0]; const waitTime = (this.perSeconds * 1000) - (now - oldestRequest); await new Promise(resolve => setTimeout(resolve, waitTime)); } this.requests.push(Date.now()); } } // Usage const limiter = new RateLimiter(3000, 3600); // 3000 requests per hour async function makeRequest(url) { await limiter.throttle(); return fetch(url); } ``` **3. Implement retry with exponential backoff:** ```javascript async function fetchWithRetry(url, maxRetries = 3) { for (let i = 0; i < maxRetries; i++) { try { const response = await fetch(url); if (response.status === 429) { const retryAfter = response.headers.get('Retry-After') || Math.pow(2, i); console.log(`Rate limited. Retrying after ${retryAfter} seconds...`); await sleep(retryAfter * 1000); continue; } return response; } catch (error) { if (i === maxRetries - 1) throw error; await sleep(Math.pow(2, i) * 1000); } } } ``` **4. Optimisation strategies:** | Strategy | Savings | How | | -------------------- | ------- | ---------------------------------------- | | Use includes | 50-80% | Combine related data in one request | | Cache reference data | 30-50% | Store types, states, leagues locally | | Batch operations | 40-60% | Use multi-ID endpoints where available | | Smart polling | 30-40% | Only poll live matches, reduce frequency | **Example - Before & after optimisation:** ```javascript // ❌ Before: 50 API calls for 10 fixtures for (const fixtureId of fixtureIds) { const fixture = await fetch(`/fixtures/${fixtureId}`); const team1 = await fetch(`/teams/${fixture.team1_id}`); const team2 = await fetch(`/teams/${fixture.team2_id}`); const events = await fetch(`/fixtures/${fixtureId}/events`); const stats = await fetch(`/fixtures/${fixtureId}/statistics`); } // ✅ After: 2 API calls for 10 fixtures const fixtures = await fetch( `/fixtures/multi/${fixtureIds.join(',')}?include=participants;events;statistics.type` ); // Then fetch types once and cache const types = await fetch('/types'); ``` **5. Monitor your usage:** ```javascript function logRateLimit(response) { const remaining = response.rate_limit.remaining; const total = response.rate_limit.resets_in_seconds; console.log(`Rate limit: ${remaining} requests remaining`); if (remaining < 100) { console.warn('⚠️ Low on API calls! Optimize your requests.'); } } ``` 📖 **Related:** [Rate Limiting Guide](https://docs.sportmonks.com/v3/api/rate-limit) | [Includes Tutorial](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes) | [Best Practices](https://docs.sportmonks.com/v3/welcome/best-practices) #### 500: Internal server error 🔧 **What it means:** Something went wrong on our servers. **When this happens:** * Temporary server issue * Database connectivity problem * Unexpected data format causing server error * Service maintenance or deployment **Example error response:** ```json { "error": "Internal Server Error", "message": "An unexpected error occurred. Our team has been notified.", "error_id": "err_abc123xyz" } ``` **How to handle:** **1. Implement retry logic:** ```javascript async function fetchWithRetry(url, maxRetries = 3) { for (let i = 0; i < maxRetries; i++) { try { const response = await fetch(url); if (response.status === 500) { if (i < maxRetries - 1) { console.log(`Server error. Retrying (${i + 1}/${maxRetries})...`); await sleep(Math.pow(2, i) * 1000); // Exponential backoff continue; } } return response; } catch (error) { if (i === maxRetries - 1) throw error; } } } ``` **2. Check API status:** * Visit [Sportmonks Status Page](https://status.sportmonks.com) (if available) * Check for maintenance announcements * Verify if issue is widespread or isolated **3. Contact support (if persistent):** ```javascript if (response.status === 500) { const errorDetails = { timestamp: new Date().toISOString(), endpoint: url, error_id: response.error_id, request_id: response.headers.get('X-Request-ID') }; console.error('Persistent 500 error:', errorDetails); // Send to support: support@sportmonks.com } ``` **4. Graceful degradation:** ```javascript async function getFixtures(fallbackData) { try { const response = await fetch(url); if (response.status === 500) { console.warn('Server error. Using cached data.'); return fallbackData; // Use cached or default data } return await response.json(); } catch (error) { console.error('Complete failure:', error); return fallbackData; } } ``` 📖 **Related:** [Best Practices](https://docs.sportmonks.com/v3/welcome/best-practices) | [Contact Support](https://www.sportmonks.com/contact-support/) ### Common error scenarios #### Scenario 1: "Data is missing" **Problem:** Response is 200 OK but data is empty or missing fields. **Not an error code issue!** This is usually because: * Resource not in your plan → Check [plan access](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/data-features-per-league) * Missing includes → Add necessary includes to request * Filtering too strict → Review [filter syntax](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/filter-and-select-fields) #### Scenario 2: CORS Errors (Frontend) **Problem:** "CORS policy: No 'Access-Control-Allow-Origin' header" **Solution:** This isn't an API error - use a backend proxy: ```javascript // ❌ Don't do this - frontend direct call fetch('https://api.sportmonks.com/v3/football/fixtures?api_token=YOUR_TOKEN') // ✅ Do this - call your backend fetch('/api/fixtures') // Your backend proxies to Sportmonks ``` 📖 **Learn more:** [CORS Best Practices](https://docs.sportmonks.com/v3/welcome/best-practices#cors-and-frontend-security) #### Scenario 3: Timeout errors **Problem:** Request times out with no response. **Solutions:** * Reduce includes complexity * Add pagination to large requests * Check your network connectivity * Increase timeout threshold in your code ### Error handling code examples #### Complete Example (JavaScript/Node.js) {% tabs %} {% tab title="JavaScript" %} ```javascript class SportmonksAPI { constructor(apiToken) { this.apiToken = apiToken; this.baseURL = 'https://api.sportmonks.com/v3/football'; } async request(endpoint, params = {}) { const url = new URL(`${this.baseURL}${endpoint}`); url.searchParams.append('api_token', this.apiToken); Object.entries(params).forEach(([key, value]) => { url.searchParams.append(key, value); }); try { const response = await fetch(url.toString()); const data = await response.json(); // Handle different status codes switch (response.status) { case 200: return { success: true, data: data.data }; case 400: throw new Error(`Bad Request: ${data.message || 'Invalid parameters'}`); case 401: throw new Error('Unauthorized: Check your API token'); case 403: throw new Error(`Forbidden: ${data.message || 'Resource not in your plan'}`); case 404: throw new Error(`Not Found: Resource doesn't exist`); case 429: const retryAfter = data.retry_after || 60; throw new Error(`Rate Limited: Retry after ${retryAfter} seconds`); case 500: throw new Error('Server Error: Try again later or contact support'); default: throw new Error(`Unexpected error: ${response.status}`); } } catch (error) { console.error('API Error:', error.message); throw error; } } } // Usage const api = new SportmonksAPI(process.env.SPORTMONKS_TOKEN); try { const fixtures = await api.request('/fixtures', { filters: 'fixtureLeagues:501', include: 'participants' }); console.log(fixtures); } catch (error) { // Handle error appropriately in your app console.error('Failed to fetch fixtures:', error); } ``` {% endtab %} {% tab title="Python" %} ```python import requests import time from typing import Optional, Dict, Any class SportmonksAPI: def __init__(self, api_token: str): self.api_token = api_token self.base_url = 'https://api.sportmonks.com/v3/football' def request(self, endpoint: str, params: Optional[Dict] = None, retry_count: int = 0) -> Dict[str, Any]: """Make API request with error handling""" url = f"{self.base_url}{endpoint}" # Add API token to params if params is None: params = {} params['api_token'] = self.api_token try: response = requests.get(url, params=params, timeout=30) # Handle different status codes if response.status_code == 200: return {'success': True, 'data': response.json().get('data')} elif response.status_code == 400: error_data = response.json() raise ValueError(f"Bad Request: {error_data.get('message', 'Invalid parameters')}") elif response.status_code == 401: raise PermissionError('Unauthorized: Check your API token') elif response.status_code == 403: error_data = response.json() raise PermissionError(f"Forbidden: {error_data.get('message', 'Resource not in your plan')}") elif response.status_code == 404: raise LookupError('Not Found: Resource does not exist') elif response.status_code == 429: if retry_count < 3: retry_after = response.json().get('retry_after', 60) print(f"Rate limited. Retrying after {retry_after} seconds...") time.sleep(retry_after) return self.request(endpoint, params, retry_count + 1) else: raise Exception('Rate limit exceeded. Max retries reached.') elif response.status_code == 500: if retry_count < 2: wait_time = 2 ** retry_count print(f"Server error. Retrying after {wait_time} seconds...") time.sleep(wait_time) return self.request(endpoint, params, retry_count + 1) else: raise Exception('Server error persists. Contact support.') else: raise Exception(f"Unexpected error: HTTP {response.status_code}") except requests.exceptions.Timeout: raise TimeoutError('Request timed out') except requests.exceptions.ConnectionError: raise ConnectionError('Failed to connect to API') # Usage api = SportmonksAPI(os.environ.get('SPORTMONKS_TOKEN')) try: fixtures = api.request('/fixtures', { 'filters': 'fixtureLeagues:501', 'include': 'participants' }) print(f"Found {len(fixtures['data'])} fixtures") except Exception as error: print(f"Error: {error}") ``` {% endtab %} {% endtabs %} ### See also * [Rate Limiting Guide](https://docs.sportmonks.com/v3/api/rate-limit) - Understand and optimize rate limits * [Authentication](https://docs.sportmonks.com/v3/welcome/authentication) - Setting up API access * [Best Practices](https://docs.sportmonks.com/v3/welcome/best-practices) - Build robust applications * [Request Options](https://docs.sportmonks.com/v3/api/request-options) - Available query parameters * [Contact Support](https://www.sportmonks.com/contact-support/) - Get help when needed \ **Need help?** Contact or use the chat widget. # Include Exceptions Whenever you make a request that is accepted and gives an error based on **includes** you can check the status code or name in the table below for more information. The description will show more details about how the error is created and what possible steps you can take to avoid these kind of errors. | Status | Name | Description | | ------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `5000` | Include not allowed | This include is not allowed on this entity, try removing the include from the request. Check the list of includes that are allowed for this [endpoint](/v3/endpoints-and-entities/endpoints). | | `5001` | Include not found | This include is not available in the API, please remove the inlcude from the request. Check the docs for the requested entity to check all the available includes. | | `5008` | Include depth | You have reached the limit on [nested includes](/v3/tutorials-and-guides/tutorials/enrich-your-response/nested-includes). Try removing the last nested include or try other endpoints to reduce the amount of nested includes. | | `5013` | Include not available | This include is not available on the requested entity. Check the docs for the requested entity to check all the available includes. | # Filtering and Complexity Exceptions Whenever you make a request that is accepted and gives an error based on **filters and/or complexity** you can check the status code or name in the table below for more information. The description will show more details about how the error is created and what possible steps you can take to avoid these kind of errors. | Status | Name | Description | | ------ | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `5004` | Query complexity | This query (includes,filters etc) is too complex to process by the server, please check [query complexity](/v3/api/request-options) for more information. | | `5006` | Invalid query parameter | This parameter is not allowed on the request, please remove this parameter before trying again. | | `5010` | Inapplicable Filter | This filter cannot be used on this request, please check if the filter is correct or remove the filter. Check [filtering](/v3/tutorials-and-guides/tutorials/filter-and-select-fields/filtering) for more information. | # Other Exceptions Whenever you make a request that is accepted and gives an error you can check the status code or name in the table below for more information. The description will show more details about how the error is created and what possible steps you can take to avoid these kind of errors. | Status | Name | Description | | ------ | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `5003` | Pagination Limit | The page you are requesting does not exist. Please change the \&page= attribute to another value. | | `5005` | Rate limit | You have reached the rate limit of your plan. This resets every hour. If you still hit the rate limit you can always add more API calls on my.sportmonks.com. Check [Rate Limit](/v3/api/rate-limit) for more information. | | `5007` | Insufficient Resources | You do not have access to this resource in your current subscription. If you would like to add more resources please update your subscription or contact support. | | `5002` | Insufficient Includes | You do not have access to this include in your current subscription. If you would like to add more includes please update your subscription or contact support. | # Code libraries ### Community libraries To help developers integrate the Sportmonks Football API more efficiently, the community has contributed various SDKs and packages across different programming languages. Below is a collection of available resources: #### Laravel * **sportmonks-fpicosm** ([GitHub Repository](https://github.com/fpicosm/sportmonks))\ A Laravel package for interacting with the Sportmonks Football API, making it easier to fetch and process football data. ### Contribute your own library We encourage developers to build and share their own libraries, SDKs, and integrations for the Sportmonks Football API. If you've created a package in any programming language, feel free to submit it for inclusion in this list. To contribute: 1. Publish your package on GitHub or a relevant package registry (e.g., PyPI, npm, Maven). 2. Share the repository link with us by [contacting our support team](https://www.sportmonks.com/contact-support/). 3. Ensure that your library is well-documented and adheres to best practices for API integration. By contributing, you help expand the ecosystem and make it easier for other developers to integrate football data into their projects! # Translations (beta) Welcome to the API Translations documentation! Here, we'll explore how you can enhance the user experience of your application by incorporating localised content using Sportmonks Football API. By utilising powerful translation capabilities, you can provide content in your preferred language: increasing the user experience of your football application. Let’s dive in on what can be translated and how it works. ### Which API fields are translated? Our Football API 3.0 now supports translations for entities with textual fields (e.g names). Currently, you can find translations for the below list of entities. Please keep in mind that we are still translating and we are working on enriching the list. | Entities | | --------- | | city | | continent | | country | | fixture | | group | | league | | player | | stage | | state | | team | | type | | venue | ### Which languages are supported? The high-anticipated translations are now available for selected languages: | Languague | Shortcode | | ---------------- | --------- | | Chinese | `zh` | | Japanese | `ja` | | Russian | `ru` | | Persian | `fa` | | Arabic | `ar` | | Greek | `el` | | Italian | `it` | | Spanish | `es` | | French | `fr` | | Hungarian | `hu` | | German | `de` | | Ukrainian | `ua` | | Central Kurdish | `ckb` | | Kurdish Kurmanji | `kmr` | {% hint style="info" %} **Please note:** The feature is still in beta; other languages will be added soon. Spanish, Portuguese and French are at the top of our backlog. Interested in another language? [Let us know](https://www.sportmonks.com/contact-support/). {% endhint %} ### How does it work? Integrating translations is seamless. Utilise the locale parameter with the shortcode of the desired country to fetch content in the preferred language. The Football API will respond with translated data, efficiently presenting relevant information to your users. For example, from the livescores endpoint, you want to display the team names in Arabic: {% tabs %} {% tab title="Example request" %} ```javascript https://api.sportmonks.com/v3/football/livescores/inplay?api_token=YOURTOKEN&locale=ar ``` {% endtab %} {% tab title="Example response" %} ```javascript { "data": [ { "id": 18881507, "sport_id": 1, "league_id": 24, "season_id": 21931, "stage_id": 77465029, "group_id": null, "aggregate_id": null, "round_id": null, "state_id": 11, "venue_id": null, "name": "إبسويش واندرز ضد هيستون", "starting_at": "2023-08-08 18:45:00", "result_info": null, "leg": "1/1", "details": null, "length": 90, "placeholder": false, "has_odds": false, "starting_at_timestamp": 1691520300 }, { "id": 18875447, "sport_id": 1, "league_id": 612, "season_id": 21861, "stage_id": 77464703, "group_id": 249133, "aggregate_id": null, "round_id": 310453, "state_id": 22, "venue_id": null, "name": "تشيرنيهيف ضد إنهوليتس.", "starting_at": "2023-08-07 09:00:00", "result_info": null, "leg": "1/1", "details": null, "length": 90, "placeholder": false, "has_odds": true, "starting_at_timestamp": 1691398800 }, ///and more! ``` {% endtab %} {% endtabs %} {% hint style="warning" %} Important to note: if there is no translation available, the API will fall back on the default supported language: English {% endhint %} ### Do you have any suggestions or improvements? As mentioned, the translations are still in beta. You can contribute to the product by adding suggestions or improvements via [my.sportmonks.](https://sportmonks.lt.acemlnb.com/Prod/link-tracker?notrack=1\&redirectUrl=aHR0cHMlM0ElMkYlMkZteS5zcG9ydG1vbmtzLmNvbQ==\&sig=HyPNYt5MzisXnDSq9gjTwBgz23aCU4UDjUrza1JJx8Gt\&iat=1691155826\&a=%7C%7C66404002%7C%7C\&account=sportmonks%2Eactivehosted%2Ecom\&email=aRCZZu5IQcsf4UXgq8zKhm%2FZrS3T1eV6Zlb52OBMqjQMtJ6jyQ%3D%3D%3AhiAm5eGK6aNqinxudkZx9JJmQKrXiybO\&s=11b019a0d9e1e46e2283697cd5754692\&i=695A854A0A5377) {% hint style="info" %} Try it out, share your feedback, and contribute to its refinement on [my.sportmonks](https://sportmonks.lt.acemlnb.com/Prod/link-tracker?notrack=1\&redirectUrl=aHR0cHMlM0ElMkYlMkZteS5zcG9ydG1vbmtzLmNvbQ==\&sig=HyPNYt5MzisXnDSq9gjTwBgz23aCU4UDjUrza1JJx8Gt\&iat=1691155826\&a=%7C%7C66404002%7C%7C\&account=sportmonks%2Eactivehosted%2Ecom\&email=aRCZZu5IQcsf4UXgq8zKhm%2FZrS3T1eV6Zlb52OBMqjQMtJ6jyQ%3D%3D%3AhiAm5eGK6aNqinxudkZx9JJmQKrXiybO\&s=11b019a0d9e1e46e2283697cd5754692\&i=695A854A0A5377) {% endhint %}
# Demo response files Alongside our [tutorials ](https://docs.sportmonks.com/football/tutorials-and-guides/tutorials)and [how-to guides](https://docs.sportmonks.com/football/tutorials-and-guides/guides), we provide example JSON responses you can download directly. These sample files show you exactly what our endpoints return so you can: * Understand data structures before coding * Mock endpoints for testing and development * Plan database models and API integrations > 💡 Each example request below links to a real API call. Replace `YOUR_TOKEN` with your actual API token to test it yourself. ## **Fixtures** ### **Match and player statistics, lineups and events** #### **EPL Match Week 10, 2025/2026 season:** Nottingham Forest **- Manchester United** Request with the all match and player statistics, events and full line-up. ```http https://api.sportmonks.com/v3/football/fixtures/19427552?api_token=YOUR_TOKEN&include=statistics.type;lineups.details.type;events.type ``` {% file src="/files/GoLyTsfDHjuH0rJn4org" %} {% hint style="danger" %} Including `.type` is not recommended as an include on any endpoint. Types are used throughout the entire API. We recommend retrieving all types from the types endpoint and storing them in your database or other data structure. Only include the type if no other option is available or when testing the API. {% endhint %} ### **Pre-match odds from bet365** #### **La Liga Match Week 10, 2025/2026 season: Real Madrid - Barcelona (El Classico)** Request to retrieve pre-match odds for the first El Classico of the 2025/2026 season. ```http https://api.sportmonks.com/v3/football/fixtures/19439347?api_token=YOUR_TOKEN&include=odds&filters=bookmakers:23 ``` {% file src="/files/lcbg0GCWeTdeuDt1IIIF" %} ## **Team** ### **Team season statistics** #### **EPL 2025/2026 season: Manchester City team statistics** Request to retrieve the season statistics of Manchester City for the CL 2025/2026 season. ```http https://api.sportmonks.com/v3/football/teams/9?api_token=YOUR_TOKEN&include=statistics.details.type&filters=teamStatisticSeasons:21638 ``` {% file src="/files/raeEjj7J5uUoXtit8SRB" %} {% hint style="danger" %} Including `.type` is not recommended as an include on any endpoint. Types are used throughout the entire API. We recommend retrieving all types from the types endpoint and storing them in your database or other data structure. Only include the type if no other option is available or when testing the API. {% endhint %} ### **Team season squads and statistics** #### **Bundesliga 2025/2026 season: Bayern Munich squad** Request to retrieve the squad and statistics of Bayern Munich for the Bundesliga 2025/2026 season. ```http https://api.sportmonks.com/v3/football/squads/seasons/25646/teams/503?api_token=YOUR_TOKEN&include=player;details.type ``` {% file src="/files/UJnphw0gGIaahbkZW4Hu" %} {% hint style="danger" %} Including `.type` is not recommended as an include on any endpoint. Types are used throughout the entire API. We recommend retrieving all types from the types endpoint and storing them in your database or other data structure. Only include the type if no other option is available or when testing the API. {% endhint %} ## **Player** ### **Player season statistics** #### **Bundesliga 2025/2025 season: Harry Kane statistics** Request to retrieve the statistics of Harry Kane for the Bundesliga 2025/2026 season. ```http https://api.sportmonks.com/v3/football/players/997?api_token=YOUR_TOKEN&include=statistics.details.type&filters=playerStatisticSeasons:21638 ``` {% file src="/files/BuKiEQdjbY281OeQvWM2" %} {% hint style="danger" %} Including `.type` is not recommended as an include on any endpoint. Types are used throughout the entire API. We recommend retrieving all types from the types endpoint and storing them in your database or other data structure. Only include the type if no other option is available or when testing the API. {% endhint %} ## **Standings** ### **Domestic League Standings** #### **Ligue 1 2025/2026 season standings** Request to retrieve the standings of the French Ligue 1 2025/2026 seasonn. ```http https://api.sportmonks.com/v3/football/standings/seasons/21646?api_token=YOUR_TOKEN&include=participant;rule;details.type ``` {% file src="/files/g3NA58W105Hu84QntbYa" %} {% hint style="danger" %} Including `.type` is not recommended as an include on any endpoint. Types are used throughout the entire API. We recommend retrieving all types from the types endpoint and storing them in your database or other data structure. Only include the type if no other option is available or when testing the API. {% endhint %} ### **International Cup Standings** #### **World Cup 2026** Qualification Europe Request to retrieve the group standings of the World Cup 2026 qualifying rounds in Europe. ```http https://api.sportmonks.com/v3/football/standings/seasons/21887?api_token=YOUR_TOKEN&include=participant;rule;details.type ``` {% file src="/files/2LG1Arbp9PiR3MqL1Ym4" %} {% hint style="danger" %} Including `.type` is not recommended as an include on any endpoint. Types are used throughout the entire API. We recommend retrieving all types from the types endpoint and storing them in your database or other data structure. Only include the type if no other option is available or when testing the API. {% endhint %} # Data corrections ## How do we handle data corrections? Our in-house data collection platform manages all of our data. Our dedicated scout teams from all over the world add, manage and validate the data collected by this platform. We collaborate with high-class data partners to ensure our football data is reliable and always up to date. However, since data is also human work, errors or inconsistencies may occur. To ensure the highest quality of football data, we have a mandatory process for promptly and effectively handling data corrections. ### Data verification and validation Before making any updates or corrections, we employ a rigorous verification and validation process. Our dedicated team of data experts reviews and cross-checks the information from our data scouts and professional data partners. Once a data correction is reported or identified, our data correction team immediately investigates the issue and takes the necessary steps to fix it. We have a system in place to identify the priority of the data error and fix it accordingly. ### Continuous improvement We are committed to continuous improvement and strive to enhance the accuracy and reliability of our data. To identify areas for improvement, we regularly review our internal processes, systems, and feedback mechanisms. By leveraging user feedback and utilising the latest technologies, we aim to provide the most comprehensive and error-free data in the sports field. ***We’re dedicated to maintaining the highest data quality and reliability standards.*** ### Error Reporting We greatly value the feedback and contributions from our users in identifying any inaccuracies or errors in our data. We encourage you to notify us via ### Further questions and legal information Please refer to our [Terms of Service](https://www.sportmonks.com/terms-of-service/) for additional details regarding usage, disclaimers, or other legal matters. If you have further questions, please consult this document for comprehensive information. # Endpoints A list of all our available endpoints ## Endpoints A consolidated overview of all Football API 3.0 endpoints, grouped by functional area. Use this page when you want to: * See **which endpoints exist** for a given domain (fixtures, teams, odds, xG, news, etc.) * Quickly **jump into the detailed reference** for a specific endpoint * Discover related capabilities you might not be using yet For request syntax, query parameters, examples, and response schemas, open the linked endpoint pages. {% hint style="info" %} If you prefer an interactive reference, you can also use the official Postman collection, which contains a complete and always up‑to‑date list of endpoints. {% endhint %} *** ### Livescores * [GET Inplay Livescores](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/livescores/get-inplay-livescores) * [GET All Livescores](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/livescores/get-all-livescores) * [GET Latest Updated Livescores](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/livescores/get-latest-updated-livescores) *** ### Fixtures * [GET All Fixtures](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/fixtures/get-all-fixtures) * [GET Fixture by ID](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/fixtures/get-fixture-by-id) * [GET Fixtures by Multiple IDs](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/fixtures/get-fixtures-by-multiple-ids) * [GET Fixtures by Date](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/fixtures/get-fixtures-by-date) * [GET Fixtures by Date Range](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/fixtures/get-fixtures-by-date-range) * [GET Fixtures by Date Range for Team](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/fixtures/get-fixtures-by-date-range-for-team) * [GET Fixtures by Head To Head](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/fixtures/get-fixtures-by-head-to-head) * [GET Fixtures by Search by Name](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/fixtures/get-fixtures-by-search-by-name) * [GET Upcoming Fixtures by Market ID](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/fixtures/get-upcoming-fixtures-by-market-id) * [GET Upcoming Fixtures by TV Station ID](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/fixtures/get-upcoming-fixtures-by-tv-station-id) * [GET Past Fixtures by TV Station ID](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/fixtures/get-past-fixtures-by-tv-station-id) * [GET Latest Updated Fixtures](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/fixtures/get-latest-updated-fixtures) *** ### States * [GET All States](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/states/get-all-states) * [GET State by ID](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/states/get-state-by-id) *** ### Types * [GET All Types](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/types/get-all-types) * [GET Type by ID](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/types/get-type-by-id) * [GET Type by Entity](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/types/get-type-by-entity) *** ### Leagues * [GET All Leagues](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/leagues/get-all-leagues) * GET League by ID * [GET Leagues by Live](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/leagues/get-leagues-by-live) * [GET Leagues by Fixture Date](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/leagues/get-leagues-by-fixture-date) * [GET Leagues by Country ID](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/leagues/get-leagues-by-country-id) * [GET Leagues Search by Name](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/leagues/get-leagues-search-by-name) * [GET All Leagues by Team ID](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/leagues/get-all-leagues-by-team-id) * [GET Current Leagues by Team ID](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/leagues/get-current-leagues-by-team-id) *** ### Seasons * [GET All Seasons](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/seasons/get-all-seasons) * [GET Seasons by ID](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/seasons/get-seasons-by-id) * [GET Seasons by Team ID](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/seasons/get-seasons-by-team-id) * [GET Seasons by Search by Name](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/seasons/get-seasons-by-search-by-name) *** ### Statistics * [GET Season Statistics by Participant](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/statistics/get-season-statistics-by-participant) * [GET Stage Statistics by ID](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/statistics/get-stage-statistics-by-id) * [GET Round Statistics by ID](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/statistics/get-round-statistics-by-id) *** ### Schedules * [GET Schedules by Season ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/schedules/get-schedules-by-season-id) * [GET Schedules by Team ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/schedules/get-schedules-by-team-id) * [GET Schedules by Season ID and Team ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/schedules/get-schedules-by-season-id-and-team-id) *** ### Stages * [GET All Stages](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/stages/get-all-stages) * [GET Stage by ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/stages/get-stage-by-id) * [GET Stages by Season ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/stages/get-stages-by-season-id) * [GET Stages by Search by Name](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/stages/get-stages-by-search-by-name) *** ### Rounds * [GET All Rounds](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/rounds/get-all-rounds) * [GET Round by ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/rounds/get-round-by-id) * [GET Rounds by Season ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/rounds/get-rounds-by-season-id) * [GET Rounds by Search by Name](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/rounds/get-rounds-by-search-by-name) *** ### Standings * [GET All Standings](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/standings/get-all-standings) * [GET Standings by Season ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/standings/get-standings-by-season-id) * [GET Standings by Round ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/standings/get-standings-by-round-id) * [GET Standing Correction by Season ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/standings/get-standing-correction-by-season-id) * [GET Live Standings by League ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/standings/get-live-standings-by-league-id) *** ### Topscorers * [GET Topscorers by Season ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/topscorers/get-topscorers-by-season-id) * [GET Topscorers by Stage ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/topscorers/get-topscorers-by-stage-id) *** ### Teams * [GET All Teams](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/teams/get-all-teams) * [GET Team by ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/teams/get-team-by-id) * [GET Teams by Country ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/teams/get-teams-by-country-id) * [GET Teams by Season ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/teams/get-teams-by-season-id) * [GET Teams by Search by Name](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/teams/get-teams-by-search-by-name) *** ### Players * [GET All Players](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/players/get-all-players) * [GET Player by ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/players/get-player-by-id) * [GET Players by Country ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/players/get-players-by-country-id) * [GET Players by Search by Name](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/players/get-players-by-search-by-name) * [GET Last Updated Players](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/players/get-last-updated-players) *** ### Team Squads * [GET Team Squad by Team ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/team-squads/get-team-squad-by-team-id) * [GET Extended Team Squad by Team ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/team-squads/get-extended-team-squad-by-team-id) * [GET Team Squad by Team and Season ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/team-squads/get-team-squad-by-team-and-season-id) *** ### Match Facts (beta) * [GET All available Match Facts](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/match-facts-beta/get-all-available-match-facts) * [GET Match Facts by Fixture ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/match-facts-beta/get-match-facts-by-fixture-id) * [GET Match Facts by Date Range](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/match-facts-beta/get-match-facts-by-date-range) * [GET Match Facts by League ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/match-facts-beta/get-match-facts-by-league-id) *** ### Team Rankings (beta) * [GET All Team Rankings](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/team-rankings-beta/get-all-team-rankings) * [GET Team Rankings by Team ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/team-rankings-beta/get-team-rankings-by-team-id) * [GET Team Rankings by Date](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/team-rankings-beta/get-team-rankings-by-date) *** ### Team of the Week (TOTW) (beta) * [GET All available TOTWs](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/team-of-the-week-totw-beta/get-all-available-totws) * [GET TOTW per Round](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/team-of-the-week-totw-beta/get-totw-per-round) * [GET Latest TOTW](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/team-of-the-week-totw-beta/get-latest-totw) *** ### Coaches * [GET All Coaches](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/coaches/get-all-coaches) * [GET Coach by ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/coaches/get-coach-by-id) * [GET Coaches by Country ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/coaches/get-coaches-by-country-id) * [GET Coaches Search by Name](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/coaches/get-coaches-search-by-name) * [GET Last Updated Coaches](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/coaches/get-last-updated-coaches) *** ### Referees * [GET All Referees](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/referees/get-all-referees) * [GET Referee by ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/referees/get-referee-by-id) * [GET Referees by Country ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/referees/get-referees-by-country-id) * [GET Referees by Season ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/referees/get-referees-by-season-id) * [GET Referees Search by Name](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/referees/get-referees-search-by-name) *** ### Transfers * [GET All Transfers](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/transfers/get-all-transfers) * [GET Transfer by ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/transfers/get-transfer-by-id) * [GET Latest Transfers](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/transfers/get-latest-transfers) * [GET Transfers Between Date Range](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/transfers/get-transfers-between-date-range) * [GET Transfers by Team ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/transfers/get-transfers-by-team-id) * [GET Transfers by Player ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/transfers/get-transfers-by-player-id) *** ### Transfer Rumours * [GET All Transfer Rumours](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/transfer-rumours/get-all-transfer-rumours) * [GET Transfer Rumours by ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/transfer-rumours/get-transfer-rumours-by-id) * [GET Transfer Rumours Between Date Range](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/transfer-rumours/get-transfer-rumours-between-date-range) * [GET Transfer Rumours by Team ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/transfer-rumours/get-transfer-rumours-by-team-id) * [GET Transfer Rumours by Player ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/transfer-rumours/get-transfer-rumours-by-player-id) *** ### Venues * [GET All Venues](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/venues/get-all-venues) * [GET Venue by ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/venues/get-venue-by-id) * [GET Venues by Season ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/venues/get-venues-by-season-id) * [GET Venues by Search by Name](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/venues/get-venues-by-search-by-name) *** ### TV Stations * [GET All TV Stations](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/tv-stations/get-all-tv-stations) * [GET TV Station by ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/tv-stations/get-tv-station-by-id) * [GET TV Stations by Fixture ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/tv-stations/get-tv-stations-by-fixture-id) *** ### Expected (xG) * [GET Expected by Team](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/expected-xg/get-expected-by-team) * [GET Expected by Player](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/expected-xg/get-expected-by-player) *** ### Premium Expected Lineups * [GET Expected Lineup by Team](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/premium-expected-lineups/get-expected-lineup-by-team) * [GET Expected Lineups by Player](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/premium-expected-lineups/get-expected-lineups-by-player) *** ### Predictions * [GET Probabilities](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/predictions/get-probabilities) * [GET Predictability by League ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/predictions/get-predictability-by-league-id) * [GET Probabilities by Fixture ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/predictions/get-probabilities-by-fixture-id) * [GET Value Bets](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/predictions/get-value-bets) * [GET Value Bets by Fixture ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/predictions/get-value-bets-by-fixture-id) *** ### Standard Odds Feed — Pre‑match Odds * [GET All Odds](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/standard-odds-feed/pre-match-odds/get-all-odds) * [GET Odds by Fixture ID](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/standard-odds-feed/pre-match-odds/get-odds-by-fixture-id) * [GET Odds by Fixture ID and Bookmaker ID](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/standard-odds-feed/pre-match-odds/get-odds-by-fixture-id-and-bookmaker-id) * [GET Odds by Fixture ID and Market ID](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/standard-odds-feed/pre-match-odds/get-odds-by-fixture-id-and-market-id) * [GET Last Updated Odds](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/standard-odds-feed/pre-match-odds/get-last-updated-odds) *** ### Standard Odds Feed — Inplay Odds * [GET All Inplay Odds](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/standard-odds-feed/inplay-odds/get-all-inplay-odds) * [GET Inplay Odds by Fixture ID](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/standard-odds-feed/inplay-odds/get-inplay-odds-by-fixture-id) * [GET Inplay Odds by Fixture ID and Bookmaker ID](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/standard-odds-feed/inplay-odds/get-inplay-odds-by-fixture-id-and-bookmaker-id) * [GET Inplay Odds by Fixture ID and Market ID](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/standard-odds-feed/inplay-odds/get-inplay-odds-by-fixture-id-and-market-id) * [GET Last Updated Inplay Odds](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/standard-odds-feed/inplay-odds/get-last-updated-inplay-odds) *** ### Premium Odds Feed — Pre‑match Odds * [GET All Premium Odds](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/premium-odds-feed/premium-pre-match-odds/get-all-premium-odds) * [GET Premium Odds by Fixture ID](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/premium-odds-feed/premium-pre-match-odds/get-premium-odds-by-fixture-id) * [GET Premium Odds by Fixture ID and Bookmaker ID](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/premium-odds-feed/premium-pre-match-odds/get-premium-odds-by-fixture-id-and-bookmaker-id) * [GET Premium Odds by Fixture ID and Market ID](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/premium-odds-feed/premium-pre-match-odds/get-premium-odds-by-fixture-id-and-market-id) * [GET Updated Premium Odds Between Time Range](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/premium-odds-feed/premium-pre-match-odds/get-updated-premium-odds-between-time-range) * [GET Updated Historical Odds Between Time Range](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/premium-odds-feed/premium-pre-match-odds/get-updated-historical-odds-between-time-range) * [GET All Historical Odds](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/premium-odds-feed/premium-pre-match-odds/get-all-historical-odds) *** ### Markets * [GET All Markets](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/markets/get-all-markets) * [GET All Premium Markets](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/markets/get-all-premium-markets) * [GET Market by ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/markets/get-market-by-id) * [GET Market by Search](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/markets/get-market-by-search) *** ### Bookmakers * [GET All Bookmakers](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/bookmakers/get-all-bookmakers) * [GET All Premium Bookmakers](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/bookmakers/get-all-premium-bookmakers) * [GET Bookmaker by ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/bookmakers/get-bookmaker-by-id) * [GET Bookmaker by Search](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/bookmakers/get-bookmaker-by-search) * [GET Bookmaker by Fixture ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/bookmakers/get-bookmaker-by-fixture-id) * [GET Bookmaker Match ID Mappings by Fixture ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/bookmakers/get-bookmaker-match-id-mappings-by-fixture-id) *** ### News * [GET Pre‑Match News](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/news/get-pre-match-news) * [GET Pre‑Match News by Season ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/news/get-pre-match-news-by-season-id) * [GET Pre‑Match News for Upcoming Fixtures](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/news/get-pre-match-news-for-upcoming-fixtures) * [GET Post‑Match News](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/news/get-post-match-news) * [GET Post‑Match News by Season ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/news/get-post-match-news-by-season-id) *** ### Rivals * [GET All Rivals](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/rivals/get-all-rivals) * [GET Rivals by Team ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/rivals/get-rivals-by-team-id) *** ### Commentaries * [GET All Commentaries](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/commentaries/get-all-commentaries) * [GET Commentaries by Fixture ID](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/commentaries/get-commentaries-by-fixture-id) *** #### What next? * New to the API? Start with the [API Structure & navigation](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/api-structure-and-navigation) and [Introduction tutorial](https://docs.sportmonks.com/v3/welcome/most-important-docs-pages). * Want to understand the data models behind these endpoints? See [Entities](https://docs.sportmonks.com/v3/endpoints-and-entities/entities). * Looking for filters, includes, and field selection? Check the [Request options](https://docs.sportmonks.com/v3/api/request-options) section. # Livescores You can obtain all the fixtures that are currently in-play via our livescores endpoints. Responses of the livescore endpoint are highly customizable because many includes are available to extend the response. You can find a list of available includes below, listed per endpoint option. The three options to retrieve livescores are: * **GET All Inplay Livescores:** returns all the inplay fixtures. * **GET All Livescores:** returns the fixtures 15 minutes before the game starts. It will also disappear 15 minutes after the game is finished. * **GET Latest Updated Livescores:** returns all livescores that have received updates within 10 seconds.

#### Include options [`sport`](https://docs.sportmonks.com/v3/core-api/) [`round`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#round) [`stage`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#stage) [`group`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#group) [`aggregate`](/v3/endpoints-and-entities/entities/fixture#aggregate) [`league`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#league) [`season`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season)[`coaches`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#coach) [`tvStations`](/v3/endpoints-and-entities/entities/other#tvstation) [`venue`](/v3/endpoints-and-entities/entities/other#venue) [`state`](/v3/endpoints-and-entities/entities/other#state) [`weatherReport`](/v3/endpoints-and-entities/entities/other#weatherreport) [`lineups`](/v3/endpoints-and-entities/entities/fixture#lineup) [`events`](/v3/endpoints-and-entities/entities/fixture#event) [`timeline`](/v3/endpoints-and-entities/entities/fixture#event) [`comments`](/v3/endpoints-and-entities/entities/other#commentary) [`trends`](/v3/endpoints-and-entities/entities/statistic#trend) [`statistics`](/v3/endpoints-and-entities/entities/statistic#fixturestatistic) [`periods`](/v3/endpoints-and-entities/entities/fixture#period) [`participants`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#team) [`inplayOdds`](/v3/endpoints-and-entities/entities/odd-and-prediction#inplayodd) [`prematchNews`](/v3/endpoints-and-entities/entities/other#news) [`postmatchNews`](/v3/endpoints-and-entities/entities/other#news) [`metadata`](/v3/endpoints-and-entities/entities/other#metadata) [`sidelined`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#sidelined)[`predictions`](/v3/endpoints-and-entities/entities/odd-and-prediction#prediction-valuebet) [`referees`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#referees) [`formations`](/v3/endpoints-and-entities/entities/fixture#formation) [`ballCoordinates`](/v3/endpoints-and-entities/entities/fixture#ballcoordinate) [`scores`](/v3/endpoints-and-entities/entities/fixture#score) [`xGFixture`](/v3/endpoints-and-entities/entities/expected) `expectedLineups` `predictedLineups` #### **Related Entities:** Get an overview and explanation of all the fields returned in the API response. The related entities for the livescores endpoints are: * [Fixture](/v3/endpoints-and-entities/entities/fixture#fixture) # GET Inplay Livescores GET All Inplay Livescores: returns all the inplay fixtures. {% tabs %} {% tab title="Base URL" %} ```javascript https://api.sportmonks.com/v3/football/livescores/inplay ``` {% endtab %} {% tab title="Example Response" %} ```json { "data": { "id": 19146701, "sport_id": 1, "league_id": 501, "season_id": 23690, "stage_id": 77471570, "group_id": null, "aggregate_id": null, "round_id": 340573, "state_id": 5, "venue_id": 8909, "name": "Celtic vs Kilmarnock", "starting_at": "2024-08-04 15:30:00", "result_info": "Celtic won after full-time.", "leg": "1/1", "details": null, "length": 90, "placeholder": false, "has_odds": true, "has_premium_odds": true, "starting_at_timestamp": 1722785400 }, ``` {% endtab %} {% tab title="Field Description" %} | Field | Description | Type | | ------------- | ------------------------------------------------ | -------------- | | id | Refers the unique id of the fixture | integer | | sport\_id | Refers to the sport the fixture is played at | integer | | league\_id | Refers to the league the fixture is played in | integer | | season\_id | Refers to the seasons the fixture is played in | integer | | stage\_id | Refers to the stage the fixture is played in | integer | | group\_id | Refers to the group the fixture is played in | integer / null | | aggregate\_id | Refers to the aggregate the fixture is played at | integer / null | | state\_id | Refers to the state the fixture is played at | integer | | round\_id | Refers to the round the fixture is played at | integer / null | | state\_id | Refers to the state the fixture is played at | integer | | venue\_id | Refers to the venue the fixture is played at | integer / null | | name | Represents the name of the participants | string / null | | starting\_at | Datetime object representing the start time | date / null | | result\_info | Represents the final result info | string / null | | leg | Represents the leg of the fixture | string | | details | Represents details about the fixture | string / null | | length | Length of the fixture (minutes) | integer / null | #### {% endtab %} {% endtabs %} {% tabs %} {% tab title="Query Parameters" %}

Name	Required?	Description
`api_token`	YES Another option is to provide the API token in the header.	Your unique API token. Ex. ?api_token=YOUR_TOKEN
`include`	NO	Enrich the API response with more data by using includes. Ex. &include=participants;events
`select`	NO	Select specific fields on the base entity. Read how to select fields in our tutorial.
`sortBy`	NO	Order by specific fields on the base entity. For more information check out this page.
`filters`	NO	Filter the API response on multiple related entities. There are static filters and dynamic filters. Please find the possibilities in the Static and Dynamic Filter tab.
`locale`	NO	Translate name fields of the API Response in your selected language. Find more information and which languages are available on our translations page.

{% endtab %} {% tab title="Static Filters" %} **Static filters** are always the same and filter in one specific way without any custom options. Each static filter is listed below and has a description of how it filters. For more information, please look at our[ Filters page](/v3/api/request-options/filtering).

Static Filters	Available on Entity	Description	Example
`ParticipantSearch`	Fixture	Filter on the matches of specific participants.	`&include=participants&filters=participantSearch:Celtic`
`todayDate`	Fixture	Filter all fixtures to find only the fixtures of today.	`&filters=todayDate`
`venues`	Fixture	Find all fixtures that are played in a specific venue.	`&include=venue&filters=venues:venueIDs` `&include=venue&filters=venues:10,12`
`IsDeleted`	Fixture	Filter on deleted fixtures only. This filter helps to keep your database in sync.	`&filters=IsDeleted`
`markets`	Odds	Filter the odds on a selection of markets separated by a comma.	`&include=odds&filters=markets:marketIDs` `&include=odds&filters=markets:12,14`
`bookmakers`	Odds	Filter the odds on a selection of bookmakers separated by a comma. (e.g: 2,14).	`&include=odds&filters=bookmakers:bookmakerIDs` `&include=odds&filters=bookmakers:2,14`
`WinningOdds`	Odds	Filter all winning odds.	`&include=odds&filters=WinningOdds`

{% endtab %} {% tab title="Dynamic Filters" %} The **dynamic filters** are based on entities and includes. Each dynamic filter uses an entity to filter on and one entity to apply the filter on. Below are examples with explanations of how filters are set up. For more information, please look at our [Filters page.](/v3/api/request-options/filtering) {% hint style="info" %} Using an include? Check their respective filters on their entity page. For example if you use `&include=participants` you can apply [team-related filters](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#team). {% endhint %}

Dynamic Filters	Available on Entity	Description	Examples
`types`	Statistics, Events, Lineup, and way more. Check this endpoint for all possibilities.	Filter the Types on a selection of Fixture statistics separated by a comma. Filter on the specific events you want to show.	`&include=statistics&filters=statisticTypes:TypeIDs` `&include=statistics&filters=statisticTypes:42,49` `&include=events&filters=eventTypes:14`
`states`	Fixtures Check this endpoint for all possibilities.	Filter the states of fixtures separated by a comma.	`&include=state&filters=fixtureStates:StateIDs` `&include=state&filters=fixtureStates:1`
`leagues`	Fixtures, Seasons, Standings, and way more. Check this endpoint for all possibilities.	Filter the fixtures based on leagues and their rounds.	`&filters=fixtureLeagues:leagueIDs` `&filters=fixtureLeagues:501,271`
`groups`	Fixtures, Standing, and more. Check this endpoint for all possibilities.	Filter the fixtures based on groups. Get their fixtures and standings.	`&include=group&filters=fixtureGroups:groupIDs` `&include=group&filters=fixtureGroups:246691`
`countries`	Coaches, Leagues, Players, Teams, and way more. Check this endpoint for all possibilities.	Filter the coaches, leagues, players and more based on countries.	`&include=coaches&filters=coachCountries:CountryIDs` `&include=coaches&filters=coachCountries:1161`
`seasons`	Statistics (players, team, coaches, referees), Standings, and way more. Check this endpoint for all possibilities.	Filter statistics, standings and topscorers based on seasons.	`&include=season.statistics&filters=seasonStatisticTypes:TypeIDs` `&include=season.statistics&filters=seasonStatisticTypes:52`

{% endtab %} {% endtabs %} ### **Filters** More information on how to use filters can be found on our tutorials on how to [filter](https://docs.sportmonks.com/football2/api/request-options/filtering). If you want more information on which filters to use you can check out the following [endpoint](/v3/core-api/endpoints/filters/get-all-entity-filters): {% hint style="info" %} ```javascript https://api.sportmonks.com/v3/my/filters/entity?api_token=YOUR_TOKEN ``` {% endhint %} ### Pagination NO ### Include depth You can use a total of `3` nested includes on this endpoint ### Include options [`sport`](https://docs.sportmonks.com/v3/core-api/) [`round`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#round) [`stage`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#stage) [`group`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#group) [`aggregate`](/v3/endpoints-and-entities/entities/fixture#aggregate) [`league`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#league) [`season`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season)[`coaches`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#coach) [`tvStations`](/v3/endpoints-and-entities/entities/other#tvstation) [`venue`](/v3/endpoints-and-entities/entities/other#venue) [`state`](/v3/endpoints-and-entities/entities/other#state) [`weatherReport`](/v3/endpoints-and-entities/entities/other#weatherreport) [`lineups`](/v3/endpoints-and-entities/entities/fixture#lineup) [`events`](/v3/endpoints-and-entities/entities/fixture#event) [`timeline`](/v3/endpoints-and-entities/entities/fixture#event) [`comments`](/v3/endpoints-and-entities/entities/other#commentary) [`trends`](/v3/endpoints-and-entities/entities/statistic#trend) [`statistics`](/v3/endpoints-and-entities/entities/statistic#fixturestatistic) [`periods`](/v3/endpoints-and-entities/entities/fixture#period) [`participants`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#team)[`inplayOdds`](/v3/endpoints-and-entities/entities/odd-and-prediction#inplayodd) [`prematchNews`](/v3/endpoints-and-entities/entities/other#news) [`postmatchNews`](/v3/endpoints-and-entities/entities/other#news) [`metadata`](/v3/endpoints-and-entities/entities/other#metadata) [`sidelined`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#sidelined)[`predictions`](/v3/endpoints-and-entities/entities/odd-and-prediction#prediction-valuebet) [`referees`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#referees) [`formations`](/v3/endpoints-and-entities/entities/fixture#formation) [`ballCoordinates`](/v3/endpoints-and-entities/entities/fixture#ballcoordinate) [`scores`](/v3/endpoints-and-entities/entities/fixture#score) [`xGFixture`](/v3/endpoints-and-entities/entities/expected) `expectedLineups` `matchfacts` `AIOverviews` **Related Entities:** Get an overview and explanation of all the fields returned in the API response. The related entities for the livescores endpoints are: * [Fixture](/v3/endpoints-and-entities/entities/fixture#fixture) ### Postman We also offer detailed postman documentation with examples and a complete up-to-date version of all our endpoints. Below is a button that lets your fork the collection or import it. \ [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316?action=collection%2Ffork\&collection-url=entityId%3D11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316%26entityType%3Dcollection%26workspaceId%3D17c720d0-d97b-42a9-9ea7-23260ed53ddf) ### Code Example {% tabs %} {% tab title="Ruby" %} ```ruby require "uri" require "net/http" url = URI("https://api.sportmonks.com/v3/football/livescores/inplay?api_token=YOUR_TOKEN") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Get.new(url) response = https.request(request) puts response.read_body ``` {% endtab %} {% tab title="Python" %} ```python import http.client conn = http.client.HTTPSConnection("api.sportmonks.com") payload = '' headers = {} conn.request("GET", "/v3/football/livescores/inplay?api_token=YOUR_TOKEN", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) ``` {% endtab %} {% tab title="PHP" %} ```php 'https://api.sportmonks.com/v3/football/livescores/inplay?api_token=YOUR_TOKEN', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', )); $response = curl_exec($curl); curl_close($curl); echo $respons ``` {% endtab %} {% tab title="Java" %} ```java OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://api.sportmonks.com/v3/football/livescores/inplay?api_token=YOUR_TOKEN") .method("GET", null) .build(); Response response = client.newCall(request).execute(); ``` {% endtab %} {% tab title="Node.js" %} ``` var unirest = require('unirest'); var req = unirest('GET', 'https://api.sportmonks.com/v3/football/livescores/inplay?api_token=YOUR_TOKEN') .end(function (res) { if (res.error) throw new Error(res.error); console.log(res.raw_body); }); ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://api.sportmonks.com/v3/football/livescores/inplay?api_token=YOUR_TOKEN" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %} # GET All Livescores Returns the fixtures 15 minutes before the game starts. It will also disappear 15 minutes after the game is finished. {% tabs %} {% tab title="Base URL" %} ```javascript https://api.sportmonks.com/v3/football/livescores ``` {% endtab %} {% tab title="Example Response" %} ```json { "data": { "id": 19146701, "sport_id": 1, "league_id": 501, "season_id": 23690, "stage_id": 77471570, "group_id": null, "aggregate_id": null, "round_id": 340573, "state_id": 5, "venue_id": 8909, "name": "Celtic vs Kilmarnock", "starting_at": "2024-08-04 15:30:00", "result_info": "Celtic won after full-time.", "leg": "1/1", "details": null, "length": 90, "placeholder": false, "has_odds": true, "has_premium_odds": true, "starting_at_timestamp": 1722785400 }, ``` {% endtab %} {% tab title="Field Description" %} | Field | Description | Type | | ------------- | ------------------------------------------------ | -------------- | | id | Refers the unique id of the fixture | integer | | sport\_id | Refers to the sport the fixture is played at | integer | | league\_id | Refers to the league the fixture is played in | integer | | season\_id | Refers to the seasons the fixture is played in | integer | | stage\_id | Refers to the stage the fixture is played in | integer | | group\_id | Refers to the group the fixture is played in | integer / null | | aggregate\_id | Refers to the aggregate the fixture is played at | integer / null | | state\_id | Refers to the state the fixture is played at | integer | | round\_id | Refers to the round the fixture is played at | integer / null | | state\_id | Refers to the state the fixture is played at | integer | | venue\_id | Refers to the venue the fixture is played at | integer / null | | name | Represents the name of the participants | string / null | | starting\_at | Datetime object representing the start time | date / null | | result\_info | Represents the final result info | string / null | | leg | Represents the leg of the fixture | string | | details | Represents details about the fixture | string / null | | length | Length of the fixture (minutes) | integer / null | #### {% endtab %} {% endtabs %} {% tabs %} {% tab title="Query Parameters" %}

Name	Required?	Description
`api_token`	YES Another option is to provide the API token in the header.	Your unique API token. Ex. ?api_token=YOUR_TOKEN
`include`	NO	Enrich the API response with more data by using includes. Ex. &include=participants;events
`select`	NO	Select specific fields on the base entity. Read how to select fields in our tutorial.
`sortBy`	NO	Order by specific fields on the base entity. For more information check out this page.
`filters`	NO	Filter the API response on multiple related entities. There are static filters and dynamic filters. Please find the possibilities in the Static and Dynamic Filter tab.
`locale`	NO	Translate name fields of the API Response in your selected language. Find more information and which languages are available on our translations page.

Static Filters	Available on Entity	Description	Example
`ParticipantSearch`	Fixture	Filter on the matches of specific participants.	`&include=participants&filters=participantSearch:Celtic`
`TodayDate`	Fixture	Filter all fixtures to find only the fixtures of today.	`&filters=todayDate`
`venues`	Fixture	Find all fixtures that are played in a specific venue.	`&include=venue&filters=venues:venueIDs` `&include=venue&filters=venues:10,12`
`IsDeleted`	Fixture	Filter on deleted fixtures only. This filter helps to keep your database in sync.	`&filters=IsDeleted`
`markets`	Odds	Filter the odds on a selection of markets separated by a comma.	`&include=odds&filters=markets:marketIDs` `&include=odds&filters=markets:12,14`
`bookmakers`	Odds	Filter the odds on a selection of bookmakers separated by a comma. (e.g: 2,14).	`&include=odds&filters=bookmakers:bookmakerIDs` `&include=odds&filters=bookmakers:2,14`
`WinningOdds`	Odds	Filter all winning odds.	`&include=odds&filters=WinningOdds`

Dynamic Filters	Available on Entity	Description	Examples
`types`	Statistics, Events, Lineup, and way more. Check this endpoint for all possibilities.	Filter the Types on a selection of Fixture statistics separated by a comma. Filter on the specific events you want to show.	`&include=statistics&filters=statisticTypes:TypeIDs` `&include=statistics&filters=statisticTypes:42,49` `&include=events&filters=eventTypes:14`
`states`	Fixtures Check this endpoint for all possibilities.	Filter the states of fixtures separated by a comma.	`&include=state&filters=fixtureStates:StateIDs` `&include=state&filters=fixtureStates:1`
`leagues`	Fixtures, Seasons, Standings, and way more. Check this endpoint for all possibilities.	Filter the fixtures based on leagues and their rounds.	`&filters=fixtureLeagues:leagueIDs` `&filters=fixtureLeagues:501,271`
`groups`	Fixtures, Standing, and more. Check this endpoint for all possibilities.	Filter the fixtures based on groups. Get their fixtures and standings.	`&include=group&filters=fixtureGroups:groupIDs` `&include=group&filters=fixtureGroups:246691`
`countries`	Coaches, Leagues, Players, Teams, and way more. Check this endpoint for all possibilities.	Filter the coaches, leagues, players and more based on countries.	`&include=coaches&filters=coachCountries:CountryIDs` `&include=coaches&filters=coachCountries:1161`
`seasons`	Statistics (players, team, coaches, referees), Standings, and way more. Check this endpoint for all possibilities.	Filter statistics, standings and topscorers based on seasons.	`&include=season.statistics&filters=seasonStatisticTypes:TypeIDs` `&include=season.statistics&filters=seasonStatisticTypes:52`

{% endtab %} {% endtabs %} ### **Filters** More information on how to use filters can be found on our tutorials on how to [filter](https://docs.sportmonks.com/football2/api/request-options/filtering). If you want more information on which filters to use you can check out the following [endpoint](/v3/core-api/endpoints/filters/get-all-entity-filters): {% hint style="info" %} ```javascript https://api.sportmonks.com/v3/my/filters/entity?api_token=YOUR_TOKEN ``` {% endhint %} ### Pagination NO ### Include depth You can use a total of `3` nested includes on this endpoint ### Include options [`sport`](https://docs.sportmonks.com/v3/core-api/) [`round`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#round) [`stage`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#stage) [`group`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#group) [`aggregate`](/v3/endpoints-and-entities/entities/fixture#aggregate) [`league`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#league) [`season`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season)[`coaches`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#coach) [`tvStations`](/v3/endpoints-and-entities/entities/other#tvstation) [`venue`](/v3/endpoints-and-entities/entities/other#venue) [`state`](/v3/endpoints-and-entities/entities/other#state) [`weatherReport`](/v3/endpoints-and-entities/entities/other#weatherreport) [`lineups`](/v3/endpoints-and-entities/entities/fixture#lineup) [`events`](/v3/endpoints-and-entities/entities/fixture#event) [`timeline`](/v3/endpoints-and-entities/entities/fixture#event) [`comments`](/v3/endpoints-and-entities/entities/other#commentary) [`trends`](/v3/endpoints-and-entities/entities/statistic#trend) [`statistics`](/v3/endpoints-and-entities/entities/statistic#fixturestatistic) [`periods`](/v3/endpoints-and-entities/entities/fixture#period) [`participants`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#team) [`inplayOdds`](/v3/endpoints-and-entities/entities/odd-and-prediction#inplayodd) [`prematchNews`](/v3/endpoints-and-entities/entities/other#news) [`postmatchNews`](/v3/endpoints-and-entities/entities/other#news) [`metadata`](/v3/endpoints-and-entities/entities/other#metadata) [`sidelined`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#sidelined)[`predictions`](/v3/endpoints-and-entities/entities/odd-and-prediction#prediction-valuebet) [`referees`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#referees) [`formations`](/v3/endpoints-and-entities/entities/fixture#formation) [`ballCoordinates`](/v3/endpoints-and-entities/entities/fixture#ballcoordinate) [`scores`](/v3/endpoints-and-entities/entities/fixture#score) [`xGFixture`](/v3/endpoints-and-entities/entities/expected) `expectedLineups` `matchfacts` `AIOverviews` ### **Related Entities:** Get an overview and explanation of all the fields returned in the API response. The related entities for the livescores endpoints are: * [Fixture](/v3/endpoints-and-entities/entities/fixture#fixture) ### Postman We also offer detailed postman documentation with examples and a complete up-to-date version of all our endpoints. Below is a button that lets your fork the collection or import it. \ [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316?action=collection%2Ffork\&collection-url=entityId%3D11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316%26entityType%3Dcollection%26workspaceId%3D17c720d0-d97b-42a9-9ea7-23260ed53ddf) ### Code Example {% tabs %} {% tab title="Ruby" %} ```ruby require "uri" require "net/http" url = URI("https://api.sportmonks.com/v3/football/livescores?api_token=YOUR_TOKEN") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Get.new(url) response = https.request(request) puts response.read_body ``` {% endtab %} {% tab title="Python" %} ```python import http.client conn = http.client.HTTPSConnection("api.sportmonks.com") payload = '' headers = {} conn.request("GET", "/v3/football/livescores?api_token=YOUR_TOKEN", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) ``` {% endtab %} {% tab title="PHP" %} ```php 'https://api.sportmonks.com/v3/football/livescores?api_token=YOUR_TOKEN', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', )); $response = curl_exec($curl); curl_close($curl); echo $respons ``` {% endtab %} {% tab title="Java" %} ```java OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://api.sportmonks.com/v3/football/livescores?api_token=YOUR_TOKEN") .method("GET", null) .build(); Response response = client.newCall(request).execute(); ``` {% endtab %} {% tab title="Node.js" %} ``` var unirest = require('unirest'); var req = unirest('GET', 'https://api.sportmonks.com/v3/football/livescores?api_token=YOUR_TOKEN') .end(function (res) { if (res.error) throw new Error(res.error); console.log(res.raw_body); }); ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://api.sportmonks.com/v3/football/livescores?api_token=YOUR_TOKEN" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %} # GET Latest Updated Livescores Returns you all livescores that have received updates within 10 seconds. {% tabs %} {% tab title="Base URL" %} ```javascript https://api.sportmonks.com/v3/football/livescores/latest ``` {% endtab %} {% tab title="Example Response" %} ```json { "data": { "id": 19146701, "sport_id": 1, "league_id": 501, "season_id": 23690, "stage_id": 77471570, "group_id": null, "aggregate_id": null, "round_id": 340573, "state_id": 5, "venue_id": 8909, "name": "Celtic vs Kilmarnock", "starting_at": "2024-08-04 15:30:00", "result_info": "Celtic won after full-time.", "leg": "1/1", "details": null, "length": 90, "placeholder": false, "has_odds": true, "has_premium_odds": true, "starting_at_timestamp": 1722785400 }, ``` {% endtab %} {% tab title="Field Description" %} | Field | Description | Type | | ------------- | ------------------------------------------------ | -------------- | | id | Refers the unique id of the fixture | integer | | sport\_id | Refers to the sport the fixture is played at | integer | | league\_id | Refers to the league the fixture is played in | integer | | season\_id | Refers to the seasons the fixture is played in | integer | | stage\_id | Refers to the stage the fixture is played in | integer | | group\_id | Refers to the group the fixture is played in | integer / null | | aggregate\_id | Refers to the aggregate the fixture is played at | integer / null | | state\_id | Refers to the state the fixture is played at | integer | | round\_id | Refers to the round the fixture is played at | integer / null | | state\_id | Refers to the state the fixture is played at | integer | | venue\_id | Refers to the venue the fixture is played at | integer / null | | name | Represents the name of the participants | string / null | | starting\_at | Datetime object representing the start time | date / null | | result\_info | Represents the final result info | string / null | | leg | Represents the leg of the fixture | string | | details | Represents details about the fixture | string / null | | length | Length of the fixture (minutes) | integer / null | #### {% endtab %} {% endtabs %} {% tabs %} {% tab title="Query Parameters" %}

Name	Required?	Description
`api_token`	YES Another option is to provide the API token in the header.	Your unique API token. Ex. ?api_token=YOUR_TOKEN
`include`	NO	Enrich the API response with more data by using includes. Ex. &include=participants;events
`select`	NO	Select specific fields on the base entity. Read how to select fields in our tutorial.
`sortBy`	NO	Order by specific fields on the base entity. For more information check out this page.
`filters`	NO	Filter the API response on multiple related entities. There are static filters and dynamic filters. Please find the possibilities in the Static and Dynamic Filter tab.
`locale`	NO	Translate name fields of the API Response in your selected language. Find more information and which languages are available on our translations page.

Static Filters	Available on Entity	Description	Example
`ParticipantSearch`	Fixture	Filter on the matches of specific participants.	`&include=participants&filters=participantSearch:Celtic`
`TodayDate`	Fixture	Filter all fixtures to find only the fixtures of today.	`&filters=todayDate`
`venues`	Fixture	Find all fixtures that are played in a specific venue.	`&include=venue&filters=venues:venueIDs` `&include=venue&filters=venues:10,12`
`IsDeleted`	Fixture	Filter on deleted fixtures only. This filter helps to keep your database in sync.	`&filters=IsDeleted`
`markets`	Odds	Filter the odds on a selection of markets separated by a comma.	`&include=odds&filters=markets:marketIDs` `&include=odds&filters=markets:12,14`
`bookmakers`	Odds	Filter the odds on a selection of bookmakers separated by a comma. (e.g: 2,14).	`&include=odds&filters=bookmakers:bookmakerIDs` `&include=odds&filters=bookmakers:2,14`
`WinningOdds`	Odds	Filter all winning odds.	`&include=odds&filters=WinningOdds`

Dynamic Filters	Available on Entity	Description	Examples
`types`	Statistics, Events, Lineup, and way more. Check this endpoint for all possibilities.	Filter the Types on a selection of Fixture statistics separated by a comma. Filter on the specific events you want to show.	`&include=statistics&filters=statisticTypes:TypeIDs` `&include=statistics&filters=statisticTypes:42,49` `&include=events&filters=eventTypes:14`
`states`	Fixtures Check this endpoint for all possibilities.	Filter the states of fixtures separated by a comma.	`&include=state&filters=fixtureStates:StateIDs` `&include=state&filters=fixtureStates:1`
`leagues`	Fixtures, Seasons, Standings, and way more. Check this endpoint for all possibilities.	Filter the fixtures based on leagues and their rounds.	`&filters=fixtureLeagues:leagueIDs` `&filters=fixtureLeagues:501,271`
`groups`	Fixtures, Standing, and more. Check this endpoint for all possibilities.	Filter the fixtures based on groups. Get their fixtures and standings.	`&include=group&filters=fixtureGroups:groupIDs` `&include=group&filters=fixtureGroups:246691`
`countries`	Coaches, Leagues, Players, Teams, and way more. Check this endpoint for all possibilities.	Filter the coaches, leagues, players and more based on countries.	`&include=coaches&filters=coachCountries:CountryIDs` `&include=coaches&filters=coachCountries:1161`
`seasons`	Statistics (players, team, coaches, referees), Standings, and way more. Check this endpoint for all possibilities.	Filter statistics, standings and topscorers based on seasons.	`&include=season.statistics&filters=seasonStatisticTypes:TypeIDs` `&include=season.statistics&filters=seasonStatisticTypes:52`

{% endtab %} {% endtabs %} ### Definition of "Latest Updated" The Latest Updated endpoint returns all fixtures whose livescore data has changed within the last 10 seconds. Specifically, it tracks changes to these eight fields: state\_id, venue\_id, name, starting\_at, starting\_at\_timestamp, result\_info, leg, and length. The update window is fixed at 10 seconds and cannot be altered. Changes to each core field mean the following: * State\_id – the match phase progressed (for example, from 1 to 2 at kick-off or from 2 to 3 at half-time) * Venue\_id – the assigned venue was updated (for example, moved from stadium A to stadium B) * Name – the fixture name text was modified (for example, team abbreviations or formatting changed) * Starting\_at – the kick-off time string was rescheduled (for example, “2024-08-04 15:30:00” to “2024-08-04 16:00:00”) * Starting\_at\_timestamp – the UNIX timestamp for kick-off was rescheduled (for example, 1722785400 to 1722787200) * Result\_info – the score summary text was updated (for example, “0-0” to “1-0”) * Leg – the leg designation changed (for example, “1/2” to “2/2”) * Length – the fixture duration changed (for example, 90 to 120 when extra time is added) > **Note****:** Only these eight fields are monitored. Changes in other data (e.g. events, lineups, odds, statistics) do **not** count toward triggering this endpoint. The 10-second window is **fixed and non-configurable**. ### Update behaviour & edge cases * On each request, the system checks the previous 10 seconds to see which fixtures had one or more of those eight fields changed. * If **no fixtures** experienced changes during that interval, the response is `200 OK` with `"data": []`. * Because of the short window, updates usually arrive in small batches. * If multiple changes occur to the same fixture within the 10-second span, you may only see the *final* post-change state, not every intermediate step. * Pay attention to **clock skew** (between your system and the API’s time) and **network jitter**, as they may cause missing updates or duplicate detections. ### Polling strategy & best practices * Recommended polling interval: **5–8 seconds**, as long as rate limits permit. * If you detect many consecutive empty responses, consider backing off (e.g. increasing the interval) to reduce unnecessary calls. * Always dedupe via your cache: ignore fixtures whose tracked fields haven’t changed. * Use exponential backoff or pauses when encountering errors, and safely resume polling without flooding. ### Caching & diff logic Your local cache should store for each fixture the current values of the eight tracked fields (state\_id, venue\_id, name, starting\_at, starting\_at\_timestamp, result\_info, leg, length). **Polling workflow:** 1. Call `GET /v3/football/livescores/latest?[params]` 2. For each fixture in the `data` array: * Compare each of the eight fields with your cached version * If **no differences** → skip/discard fixtures * If **any difference** → process this as an update and overwrite your cache 3. If you need more context (events, lineups, odds), fetch via other endpoints (e.g. Fixture by ID, Inplay Livescores) 4. Separately, maintain cached metadata (teams, leagues, venues) since they rarely change. ``` Let polling interval = 6 seconds T = now → GET latest → returns fixtures A, B → Compare with cache → apply updates for changed ones → Update cache T + 6s → GET latest → returns fixtures B, C → Process B (if changed), process C → Update cache T + 12s → GET latest → returns [] → No changes, skip processing → Optional: if many empties, slow poll rate ``` ### Filters More information on how to use filters can be found in our tutorials on how to [filter](https://docs.sportmonks.com/football2/api/request-options/filtering). If you want more information on which filters to use, you can check out the following [endpoint](/v3/core-api/endpoints/filters/get-all-entity-filters): {% hint style="info" %} ```javascript https://api.sportmonks.com/v3/my/filters/entity?api_token=YOUR_TOKEN ``` {% endhint %} ### Pagination NO ### Include depth You can use a total of `3` nested includes on this endpoint ### Include options [`sport`](https://docs.sportmonks.com/v3/core-api/) [`round`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#round) [`stage`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#stage) [`group`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#group) [`aggregate`](/v3/endpoints-and-entities/entities/fixture#aggregate) [`league`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#league) [`season`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season)[`coaches`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#coach) [`tvStations`](/v3/endpoints-and-entities/entities/other#tvstation) [`venue`](/v3/endpoints-and-entities/entities/other#venue) [`state`](/v3/endpoints-and-entities/entities/other#state) [`weatherReport`](/v3/endpoints-and-entities/entities/other#weatherreport) [`lineups`](/v3/endpoints-and-entities/entities/fixture#lineup) [`events`](/v3/endpoints-and-entities/entities/fixture#event) [`timeline`](/v3/endpoints-and-entities/entities/fixture#event) [`comments`](/v3/endpoints-and-entities/entities/other#commentary) [`trends`](/v3/endpoints-and-entities/entities/statistic#trend) [`statistics`](/v3/endpoints-and-entities/entities/statistic#fixturestatistic) [`periods`](/v3/endpoints-and-entities/entities/fixture#period) [`participants`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#team)[`inplayOdds`](/v3/endpoints-and-entities/entities/odd-and-prediction#inplayodd) [`prematchNews`](/v3/endpoints-and-entities/entities/other#news) [`metadata`](/v3/endpoints-and-entities/entities/other#metadata) [`sidelined`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#sidelined)[`predictions`](/v3/endpoints-and-entities/entities/odd-and-prediction#prediction-valuebet) [`referees`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#referees) [`formations`](/v3/endpoints-and-entities/entities/fixture#formation) [`ballCoordinates`](/v3/endpoints-and-entities/entities/fixture#ballcoordinate) [`scores`](/v3/endpoints-and-entities/entities/fixture#score)[`xGFixture`](/v3/endpoints-and-entities/entities/expected) `expectedLineups` `matchfacts` `AIOverviews` ### **Related Entities:** Get an overview and explanation of all the fields returned in the API response. The related entities for the livescores endpoints are: * [Fixture](/v3/endpoints-and-entities/entities/fixture#fixture) ### Postman We also offer detailed postman documentation with examples and a complete up-to-date version of all our endpoints. Below is a button that lets your fork the collection or import it. \ [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316?action=collection%2Ffork\&collection-url=entityId%3D11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316%26entityType%3Dcollection%26workspaceId%3D17c720d0-d97b-42a9-9ea7-23260ed53ddf) ### Code Example {% tabs %} {% tab title="Ruby" %} ```ruby require "uri" require "net/http" url = URI("https://api.sportmonks.com/v3/football/livescores/latest?api_token=YOUR_TOKEN") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Get.new(url) response = https.request(request) puts response.read_body ``` {% endtab %} {% tab title="Python" %} ```python import http.client conn = http.client.HTTPSConnection("api.sportmonks.com") payload = '' headers = {} conn.request("GET", "/v3/football/livescores/latest?api_token=YOUR_TOKEN", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) ``` {% endtab %} {% tab title="PHP" %} ```php 'https://api.sportmonks.com/v3/football/livescores/latest?api_token=YOUR_TOKEN', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', )); $response = curl_exec($curl); curl_close($curl); echo $respons ``` {% endtab %} {% tab title="Java" %} ```java OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://api.sportmonks.com/v3/football/livescores/latest?api_token=YOUR_TOKEN") .method("GET", null) .build(); Response response = client.newCall(request).execute(); ``` {% endtab %} {% tab title="Node.js" %} ``` var unirest = require('unirest'); var req = unirest('GET', 'https://api.sportmonks.com/v3/football/livescores/latest?api_token=YOUR_TOKEN') .end(function (res) { if (res.error) throw new Error(res.error); console.log(res.raw_body); }); ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://api.sportmonks.com/v3/football/livescores/latest?api_token=YOUR_TOKEN" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %} # Fixtures There are multiple options to retrieve the fixtures within your subscription. The fixtures’ endpoints are divided into 10 categories. Per endpoint, you can find the details, including base URL, parameters, include options and more. * **GET All Fixtures:** returns all the fixtures accessible within your subscription. * **GET Fixture by ID:** returns the single fixture you’ve requested by ID. * **GET Fixtures by Multiple IDs:** returns the fixtures you’ve requested by IDs. * **GET Fixture by Date Range:** returns the fixtures you’ve requested by date range. * **GET Fixture by Date:** returns the fixtures you’ve requested by a single date. * **GET Fixture by Date Range for Team:** returns the fixtures you’ve requested by date range for a specific team. * **GET Fixture by Head To Head:** returns the head to head fixtures of two teams you’ve requested. * **GET Fixture by Search by Name:** returns all fixtures that match your search query. * **GET Upcoming Fixtures by Market ID:** returns upcoming fixtures you've requested by Market ID. * **GET Fixture by Last Updated Fixtures:** returns you all the games that have received updates within 10 seconds.

{% hint style="info" %} **Please note** that you need to use one of our livescores endpoints for in-play fixtures. {% endhint %} ### Include options [`sport`](https://docs.sportmonks.com/v3/core-api/) [`round`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#round) [`stage`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#stage) [`group`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#group) [`aggregate`](/v3/endpoints-and-entities/entities/fixture#aggregate) [`league`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#league) [`season`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season)[`coaches`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#coach) [`tvStations`](/v3/endpoints-and-entities/entities/other#tvstation) [`venue`](/v3/endpoints-and-entities/entities/other#venue) [`state`](/v3/endpoints-and-entities/entities/other#state) [`weatherReport`](/v3/endpoints-and-entities/entities/other#weatherreport) [`lineups`](/v3/endpoints-and-entities/entities/fixture#lineup) [`events`](/v3/endpoints-and-entities/entities/fixture#event) [`timeline`](/v3/endpoints-and-entities/entities/fixture#event) [`comments`](/v3/endpoints-and-entities/entities/other#commentary) [`trends`](/v3/endpoints-and-entities/entities/statistic#trend) [`statistics`](/v3/endpoints-and-entities/entities/statistic#fixturestatistic) [`periods`](/v3/endpoints-and-entities/entities/fixture#period) [`participants` ](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#team)[`odds`](/v3/endpoints-and-entities/entities/odd-and-prediction#odd)[`premiumOdds`](https://docs.sportmonks.com/football/endpoints-and-entities/entities/odd-and-prediction#premium-odd) [`inplayOdds`](/v3/endpoints-and-entities/entities/odd-and-prediction#inplayodd) [`prematchNews`](/v3/endpoints-and-entities/entities/other#news) [`postmatchNews`](/v3/endpoints-and-entities/entities/other#news) [`metadata`](/v3/endpoints-and-entities/entities/other#metadata) [`sidelined`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#sidelined)[`predictions`](/v3/endpoints-and-entities/entities/odd-and-prediction#prediction-valuebet) [`referees`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#referees) [`formations`](/v3/endpoints-and-entities/entities/fixture#formation) [`ballCoordinates`](/v3/endpoints-and-entities/entities/fixture#ballcoordinate) [`scores`](/v3/endpoints-and-entities/entities/fixture#score) [`xGFixture`](/v3/endpoints-and-entities/entities/expected) [`pressure`](/v3/tutorials-and-guides/tutorials/includes/pressure-index) `expectedLineups` ### **Related Entities:** Get an overview and explanation of all the fields returned in the API response. The related entities for the fixtures endpoints are: * [Fixture](/v3/endpoints-and-entities/entities/fixture#fixture) # GET All Fixtures Returns all the fixtures accessible within your subscription. {% tabs %} {% tab title="Base URL" %} ```javascript https://api.sportmonks.com/v3/football/fixtures ``` {% endtab %} {% tab title="Example Response" %} ```json { "data": { "id": 19146701, "sport_id": 1, "league_id": 501, "season_id": 23690, "stage_id": 77471570, "group_id": null, "aggregate_id": null, "round_id": 340573, "state_id": 5, "venue_id": 8909, "name": "Celtic vs Kilmarnock", "starting_at": "2024-08-04 15:30:00", "result_info": "Celtic won after full-time.", "leg": "1/1", "details": null, "length": 90, "placeholder": false, "has_odds": true, "has_premium_odds": true, "starting_at_timestamp": 1722785400 }, ``` {% endtab %} {% tab title="Field Description" %} | Field | Description | Type | | ------------- | ------------------------------------------------ | -------------- | | id | Refers the unique id of the fixture | integer | | sport\_id | Refers to the sport the fixture is played at | integer | | league\_id | Refers to the league the fixture is played in | integer | | season\_id | Refers to the seasons the fixture is played in | integer | | stage\_id | Refers to the stage the fixture is played in | integer | | group\_id | Refers to the group the fixture is played in | integer / null | | aggregate\_id | Refers to the aggregate the fixture is played at | integer / null | | state\_id | Refers to the state the fixture is played at | integer | | round\_id | Refers to the round the fixture is played at | integer / null | | state\_id | Refers to the state the fixture is played at | integer | | venue\_id | Refers to the venue the fixture is played at | integer / null | | name | Represents the name of the participants | string / null | | starting\_at | Datetime object representing the start time | date / null | | result\_info | Represents the final result info | string / null | | leg | Represents the leg of the fixture | string | | details | Represents details about the fixture | string / null | | length | Length of the fixture (minutes) | integer / null | | {% endtab %} | | | | {% endtabs %} | | | {% tabs %} {% tab title="Query Parameters" %}

Name	Required?	Description
`api_token`	YES Another option is to provide the API token in the header.	Your unique API token. Ex. ?api_token=YOUR_TOKEN
`include`	NO	Enrich the API response with more data by using includes. Ex. &include=participants;events
`select`	NO	Select specific fields on the base entity. Read how to select fields in our tutorial.
`sortBy`	NO	Order by specific fields on the base entity. For more information check out this page.
`filters`	NO	Filter the API response on multiple related entities. There are static filters and dynamic filters. Please find the possibilities in the Static and Dynamic Filter tab.
`locale`	NO	Translate name fields of the API Response in your selected language. Find more information and which languages are available on our translations page.

Static Filters	Available on Entity	Description	Example
`participantSearch`	Fixture	Filter on the matches of specific participants.	`&include=participants&filters=participantSearch:Celtic`
`todayDate`	Fixture	Filter all fixtures to find only the fixtures of today.	`&filters=todayDate`
`venues`	Fixture	Find all fixtures that are played in a specific venue.	`&include=venue&filters=venues:venueIDs` `&include=venue&filters=venues:10,12`
`Deleted`	Fixture	Filter on deleted fixtures only. This filter helps to keep your database in sync.	`&filters=Deleted`
`IdAfter`	All	Filter all fixtures starting from a certain fixture ID. Handy when you are only interested in the most recent fixtures.	`&filters=IdAfter:fixtureID` `&filters=IdAfter:18535487`
`markets`	Odds	Filter the odds on a selection of markets separated by a comma.	`&include=odds&filters=markets:marketIDs` `&include=odds&filters=markets:12,14`
`bookmakers`	Odds	Filter the odds on a selection of bookmakers separated by a comma. (e.g: 2,14).	`&include=odds&filters=bookmakers:bookmakerIDs` `&include=odds&filters=bookmakers:2,14`
`WinningOdds`	Odds	Filter all winning odds.	`&include=odds&filters=WinningOdds`

{% endtab %} {% tab title="Dynamic Filters" %} The **dynamic filters** are based on entities and includes. Each dynamic filter uses an entity to filter on and one entity to apply the filter to. Below is an example with an explanation of how filters are set up. For more information, please look at our[ Filters page](/v3/api/request-options/filtering). {% hint style="info" %} Using an include? Check their respective filters on their entity page. For example if you use `&include=participants` you can apply [team-related filters](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#team). {% endhint %}

Dynamic Filters	Available on Entity	Description	Examples
`types`	Statistics, Events, Lineup, and way more. Check this endpoint for all possibilities.	Filter the statistics, events and more on a selection of type ids separated by a comma.	`&include=statistics.type&filters=fixturestatisticTypes:TypeIDs` `&include=statistics.type&filters=fixturestatisticTypes:42,49` `&include=events&filters=eventTypes:14` `&include=lineups.details.type&filters=lineupdetailTypes:118`
`states`	Fixtures Check this endpoint for all possibilities.	Filter the states of fixtures separated by a comma.	`&include=state&filters=fixtureStates:StateIDs` `&include=state&filters=fixtureStates:1`
`leagues`	Fixtures, Seasons, Standings, and way more. Check this endpoint for all possibilities.	Filter the fixtures based on leagues and their rounds.	`&filters=fixtureLeagues:leagueIDs` `&filters=fixtureLeagues:501,271`
`groups`	Fixtures, Standing, and more. Check this endpoint for all possibilities.	Filter the fixtures based on groups. Get their fixtures and standings.	`&include=group&filters=fixtureGroups:groupIDs` `&include=group&filters=fixtureGroups:246691`
`countries`	Coaches, Leagues, Players, Teams, and way more. Check this endpoint for all possibilities.	Filter the coaches, leagues, players and more based on countries.	`&include=coaches&filters=coachCountries:CountryIDs` `&include=coaches&filters=coachCountries:1161`
`seasons`	Statistics (players, team, coaches, referees), Standings, and way more. Check this endpoint for all possibilities.	Filter statistics, standings and topscorers based on seasons.	`&include=season.statistics&filters=seasonStatisticTypes:TypeIDs` `&include=season.statistics&filters=seasonStatisticTypes:52`

Parameter	Required	Description	Example
`order`	No	Returns fixtures ordered by id (`asc` or `desc`). Defaults to asc	&order=desc
`per_page`	No	The amount of results to return per page (max 50.). Defaults to 25.	&per_page=30
`page`	No	You can paginate using the `has_more` parameter to determine if you can still propagate through the results.	&page=2

### Include depth You can use a total of `3` nested includes on this endpoint ### Include options [`sport`](https://docs.sportmonks.com/v3/core-api/) [`round`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#round) [`stage`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#stage) [`group`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#group) [`aggregate`](/v3/endpoints-and-entities/entities/fixture#aggregate) [`league`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#league) [`season`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season)[`coaches`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#coach) [`tvStations`](/v3/endpoints-and-entities/entities/other#tvstation) [`venue`](/v3/endpoints-and-entities/entities/other#venue) [`state`](/v3/endpoints-and-entities/entities/other#state) [`weatherReport`](/v3/endpoints-and-entities/entities/other#weatherreport) [`lineups`](/v3/endpoints-and-entities/entities/fixture#lineup) [`events`](/v3/endpoints-and-entities/entities/fixture#event) [`timeline`](/v3/endpoints-and-entities/entities/fixture#event) [`comments`](/v3/endpoints-and-entities/entities/other#commentary) [`trends`](/v3/endpoints-and-entities/entities/statistic#trend) [`statistics`](/v3/endpoints-and-entities/entities/statistic#fixturestatistic) [`periods`](/v3/endpoints-and-entities/entities/fixture#period) [`currentPeriod`](https://docs.sportmonks.com/football/endpoints-and-entities/entities/fixture#period) [`participants` ](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#team)[`odds`](/v3/endpoints-and-entities/entities/odd-and-prediction#odd)[`premiumOdds`](https://docs.sportmonks.com/football/endpoints-and-entities/entities/odd-and-prediction#premium-odd) [`inplayOdds`](/v3/endpoints-and-entities/entities/odd-and-prediction#inplayodd) [`prematchNews`](/v3/endpoints-and-entities/entities/other#news) [`postmatchNews`](/v3/endpoints-and-entities/entities/other#news) [`metadata`](/v3/endpoints-and-entities/entities/other#metadata) [`sidelined`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#sidelined)[`predictions`](/v3/endpoints-and-entities/entities/odd-and-prediction#prediction-valuebet) [`referees`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#referees) [`formations`](/v3/endpoints-and-entities/entities/fixture#formation) [`ballCoordinates`](/v3/endpoints-and-entities/entities/fixture#ballcoordinate) [`scores`](/v3/endpoints-and-entities/entities/fixture#score) [`xGFixture`](/v3/endpoints-and-entities/entities/expected) [`pressure`](/v3/tutorials-and-guides/tutorials/includes/pressure-index) `expectedLineups` `predictedLineups` `matchfacts` `AIOverviews` ### **Related Entities:** Get an overview and explanation of all the fields returned in the API response. The related entities for the fixtures endpoints are: * [Fixture](/v3/endpoints-and-entities/entities/fixture#fixture) ### Postman We also offer detailed postman documentation with examples and a complete up-to-date version of all our endpoints. Below is a button that lets your fork the collection or import it. \ [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316?action=collection%2Ffork\&collection-url=entityId%3D11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316%26entityType%3Dcollection%26workspaceId%3D17c720d0-d97b-42a9-9ea7-23260ed53ddf) ### Code Example {% tabs %} {% tab title="Ruby" %} ```ruby require "uri" require "net/http" url = URI("https://api.sportmonks.com/v3/football/fixtures?api_token=YOUR_TOKEN") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Get.new(url) response = https.request(request) puts response.read_body ``` {% endtab %} {% tab title="Python" %} ```python import http.client conn = http.client.HTTPSConnection("api.sportmonks.com") payload = '' headers = {} conn.request("GET", "/v3/football/fixtures?api_token=YOUR_TOKEN", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) ``` {% endtab %} {% tab title="PHP" %} ```php 'https://api.sportmonks.com/v3/football/fixtures?api_token=YOUR_TOKEN', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', )); $response = curl_exec($curl); curl_close($curl); echo $respons ``` {% endtab %} {% tab title="Java" %} ```java OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://api.sportmonks.com/v3/football/fixtures?api_token=YOUR_TOKEN") .method("GET", null) .build(); Response response = client.newCall(request).execute(); ``` {% endtab %} {% tab title="Node.js" %} ``` var unirest = require('unirest'); var req = unirest('GET', 'https://api.sportmonks.com/v3/football/fixtures?api_token=YOUR_TOKEN') .end(function (res) { if (res.error) throw new Error(res.error); console.log(res.raw_body); }); ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://api.sportmonks.com/v3/football/fixtures?api_token=YOUR_TOKEN" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %} # GET Fixture by ID Returns the single fixture you’ve requested by ID. {% tabs %} {% tab title="Base URL" %} ```javascript https://api.sportmonks.com/v3/football/fixtures/{ID} ``` {% endtab %} {% tab title="Example Response" %} ```json { "data": { "id": 19146701, "sport_id": 1, "league_id": 501, "season_id": 23690, "stage_id": 77471570, "group_id": null, "aggregate_id": null, "round_id": 340573, "state_id": 5, "venue_id": 8909, "name": "Celtic vs Kilmarnock", "starting_at": "2024-08-04 15:30:00", "result_info": "Celtic won after full-time.", "leg": "1/1", "details": null, "length": 90, "placeholder": false, "has_odds": true, "has_premium_odds": true, "starting_at_timestamp": 1722785400 }, ``` {% endtab %} {% tab title="Field Description" %} | Field | Description | Type | | ------------- | ------------------------------------------------ | -------------- | | id | Refers the unique id of the fixture | integer | | sport\_id | Refers to the sport the fixture is played at | integer | | league\_id | Refers to the league the fixture is played in | integer | | season\_id | Refers to the seasons the fixture is played in | integer | | stage\_id | Refers to the stage the fixture is played in | integer | | group\_id | Refers to the group the fixture is played in | integer / null | | aggregate\_id | Refers to the aggregate the fixture is played at | integer / null | | state\_id | Refers to the state the fixture is played at | integer | | round\_id | Refers to the round the fixture is played at | integer / null | | state\_id | Refers to the state the fixture is played at | integer | | venue\_id | Refers to the venue the fixture is played at | integer / null | | name | Represents the name of the participants | string / null | | starting\_at | Datetime object representing the start time | date / null | | result\_info | Represents the final result info | string / null | | leg | Represents the leg of the fixture | string | | details | Represents details about the fixture | string / null | | length | Length of the fixture (minutes) | integer / null | | {% endtab %} | | | | {% endtabs %} | | | {% tabs %} {% tab title="Query Parameters" %}

Name	Required?	Description
`api_token`	YES Another option is to provide the API token in the header.	Your unique API token. Ex. ?api_token=YOUR_TOKEN
`include`	NO	Enrich the API response with more data by using includes. Ex. &include=participants;events
`select`	NO	Select specific fields on the base entity. Read how to select fields in our tutorial.
`sortBy`	NO	Order by specific fields on the base entity. For more information check out this page.
`filters`	NO	Filter the API response on multiple related entities. There are static filters and dynamic filters. Please find the possibilities in the Static and Dynamic Filter tab.
`locale`	NO	Translate name fields of the API Response in your selected language. Find more information and which languages are available on our translations page.

Static Filters	Available on Entity	Description	Example
`markets`	Odds	Filter the odds on a selection of markets separated by a comma.	`&include=odds&filters=markets:marketIDs` `&include=odds&filters=markets:12,14`
`bookmakers`	Odds	Filter the odds on a selection of bookmakers separated by a comma. (e.g: 2,14).	`&include=odds&filters=bookmakers:bookmakerIDs` `&include=odds&filters=bookmakers:2,14`
`WinningOdds`	Odds	Filter all winning odds.	`&include=odds&filters=WinningOdds`

{% endtab %} {% tab title="Dynamic Filters" %} The **dynamic filters** are based on entities and includes. Each dynamic filter uses an entity to filter on and one entity to apply the filter to. Below is an example with an explanation of how filters are set up. For more information, please look at our[ Filters page](/v3/api/request-options/filtering). {% hint style="info" %} Using an include? Check their respective filters on their entity page. For example if you use `&include=participants` you can apply [team-related filters](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#team). {% endhint %}

Dynamic Filters	Available on Entity	Description	Examples
`types`	Statistics, Events, Lineup, and way more. Check this endpoint for all possibilities.	Filter the statistics, events and more on a selection of type ids separated by a comma.	`&include=statistics.type&filters=fixturestatisticTypes:TypeIDs` `&include=statistics.type&filters=fixturestatisticTypes:42,49` `&include=events&filters=eventTypes:14` `&include=lineups.details.type&filters=lineupdetailTypes:118`
`states`	Fixtures Check this endpoint for all possibilities.	Filter the states of fixtures separated by a comma.	`&include=state&filters=fixtureStates:StateIDs` `&include=state&filters=fixtureStates:1`
`leagues`	Fixtures, Seasons, Standings, and way more. Check this endpoint for all possibilities.	Filter the fixtures based on leagues and their rounds.	`&filters=fixtureLeagues:leagueIDs` `&filters=fixtureLeagues:501,271`
`groups`	Fixtures, Standing, and more. Check this endpoint for all possibilities.	Filter the fixtures based on groups. Get their fixtures and standings.	`&include=group&filters=fixtureGroups:groupIDs` `&include=group&filters=fixtureGroups:246691`
`countries`	Coaches, Leagues, Players, Teams, and way more. Check this endpoint for all possibilities.	Filter the coaches, leagues, players and more based on countries.	`&include=coaches&filters=coachCountries:CountryIDs` `&include=coaches&filters=coachCountries:1161`
`seasons`	Statistics (players, team, coaches, referees), Standings, and way more. Check this endpoint for all possibilities.	Filter statistics, standings and topscorers based on seasons.	`&include=season.statistics&filters=seasonStatisticTypes:TypeIDs` `&include=season.statistics&filters=seasonStatisticTypes:52`

{% endtab %} {% endtabs %} ### **Filters** More information on how to use filters can be found on our tutorials on how to [filter](https://docs.sportmonks.com/football2/api/request-options/filtering). If you want more information on which filters to use you can check out the following [endpoint](/v3/core-api/endpoints/filters/get-all-entity-filters): {% hint style="info" %} ```javascript https://api.sportmonks.com/v3/my/filters/entity?api_token=YOUR_TOKEN ``` {% endhint %} ### Pagination NO ### Include depth You can use a total of `3` nested includes on this endpoint ### Include options [`sport`](https://docs.sportmonks.com/v3/core-api/) [`round`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#round) [`stage`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#stage) [`group`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#group) [`aggregate`](/v3/endpoints-and-entities/entities/fixture#aggregate) [`league`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#league) [`season`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season)[`coaches`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#coach) [`tvStations`](/v3/endpoints-and-entities/entities/other#tvstation) [`venue`](/v3/endpoints-and-entities/entities/other#venue) [`state`](/v3/endpoints-and-entities/entities/other#state) [`weatherReport`](/v3/endpoints-and-entities/entities/other#weatherreport) [`lineups`](/v3/endpoints-and-entities/entities/fixture#lineup) [`events`](/v3/endpoints-and-entities/entities/fixture#event) [`timeline`](/v3/endpoints-and-entities/entities/fixture#event) [`comments`](/v3/endpoints-and-entities/entities/other#commentary) [`trends`](/v3/endpoints-and-entities/entities/statistic#trend) [`statistics`](/v3/endpoints-and-entities/entities/statistic#fixturestatistic) [`periods`](/v3/endpoints-and-entities/entities/fixture#period) [`participants` ](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#team)[`odds`](/v3/endpoints-and-entities/entities/odd-and-prediction#odd)[`premiumOdds`](https://docs.sportmonks.com/football/endpoints-and-entities/entities/odd-and-prediction#premium-odd) [`inplayOdds`](/v3/endpoints-and-entities/entities/odd-and-prediction#inplayodd) [`prematchNews`](/v3/endpoints-and-entities/entities/other#news) [`postmatchNews`](/v3/endpoints-and-entities/entities/other#news) [`metadata`](/v3/endpoints-and-entities/entities/other#metadata) [`sidelined`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#sidelined)[`predictions`](/v3/endpoints-and-entities/entities/odd-and-prediction#prediction-valuebet) [`referees`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#referees) [`formations`](/v3/endpoints-and-entities/entities/fixture#formation) [`ballCoordinates`](/v3/endpoints-and-entities/entities/fixture#ballcoordinate) [`scores`](/v3/endpoints-and-entities/entities/fixture#score) [`xGFixture`](/v3/endpoints-and-entities/entities/expected) [`pressure`](/v3/tutorials-and-guides/tutorials/includes/pressure-index) `expectedLineups` `predictedLineups` `matchfacts` `AIOverviews` ### **Related Entities:** Get an overview and explanation of all the fields returned in the API response. The related entities for the fixtures endpoints are: * [Fixture](/v3/endpoints-and-entities/entities/fixture#fixture) ### Postman We also offer detailed postman documentation with examples and a complete up-to-date version of all our endpoints. Below is a button that lets your fork the collection or import it. \ [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316?action=collection%2Ffork\&collection-url=entityId%3D11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316%26entityType%3Dcollection%26workspaceId%3D17c720d0-d97b-42a9-9ea7-23260ed53ddf) ### Code Example {% tabs %} {% tab title="Ruby" %} ```ruby require "uri" require "net/http" url = URI("https://api.sportmonks.com/v3/football/fixtures/{ID}?api_token=YOUR_TOKEN") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Get.new(url) response = https.request(request) puts response.read_body ``` {% endtab %} {% tab title="Python" %} ```python import http.client conn = http.client.HTTPSConnection("api.sportmonks.com") payload = '' headers = {} conn.request("GET", "/v3/football/fixtures/{ID}?api_token=YOUR_TOKEN", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) ``` {% endtab %} {% tab title="PHP" %} ```php 'https://api.sportmonks.com/v3/football/fixtures/{ID}?api_token=YOUR_TOKEN', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', )); $response = curl_exec($curl); curl_close($curl); echo $respons ``` {% endtab %} {% tab title="Java" %} ```java OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://api.sportmonks.com/v3/football/fixtures/{ID}?api_token=YOUR_TOKEN") .method("GET", null) .build(); Response response = client.newCall(request).execute(); ``` {% endtab %} {% tab title="Node.js" %} ``` var unirest = require('unirest'); var req = unirest('GET', 'https://api.sportmonks.com/v3/football/fixtures/{ID}?api_token=YOUR_TOKEN') .end(function (res) { if (res.error) throw new Error(res.error); console.log(res.raw_body); }); ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://api.sportmonks.com/v3/football/fixtures/{ID}?api_token=YOUR_TOKEN" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %} # GET Fixtures by Multiple IDs Returns the fixtures you’ve requested by IDs. The maximum number of fixture IDs you can include in a single request when using this endpoint is 50. {% tabs %} {% tab title="Base URL" %} ```javascript https://api.sportmonks.com/v3/football/fixtures/multi/{IDs} ``` {% endtab %} {% tab title="Example Response" %} ```json { "id": 19146701, "sport_id": 1, "league_id": 501, "season_id": 23690, "stage_id": 77471570, "group_id": null, "aggregate_id": null, "round_id": 340573, "state_id": 5, "venue_id": 8909, "name": "Celtic vs Kilmarnock", "starting_at": "2024-08-04 15:30:00", "result_info": "Celtic won after full-time.", "leg": "1/1", "details": null, "length": 90, "placeholder": false, "has_odds": true, "has_premium_odds": true, "starting_at_timestamp": 1722785400 }, { "id": 19146702, "sport_id": 1, "league_id": 501, "season_id": 23690, "stage_id": 77471570, "group_id": null, "aggregate_id": null, "round_id": 340573, "state_id": 5, "venue_id": 219, "name": "St. Johnstone vs Aberdeen", "starting_at": "2024-08-05 19:00:00", "result_info": "Aberdeen won after full-time.", "leg": "1/1", "details": null, "length": 90, "placeholder": false, "has_odds": true, "has_premium_odds": true, "starting_at_timestamp": 1722884400 } ``` {% endtab %} {% tab title="Field Description" %} | Field | Description | Type | | ------------- | ------------------------------------------------ | -------------- | | id | Refers the unique id of the fixture | integer | | sport\_id | Refers to the sport the fixture is played at | integer | | league\_id | Refers to the league the fixture is played in | integer | | season\_id | Refers to the seasons the fixture is played in | integer | | stage\_id | Refers to the stage the fixture is played in | integer | | group\_id | Refers to the group the fixture is played in | integer / null | | aggregate\_id | Refers to the aggregate the fixture is played at | integer / null | | state\_id | Refers to the state the fixture is played at | integer | | round\_id | Refers to the round the fixture is played at | integer / null | | state\_id | Refers to the state the fixture is played at | integer | | venue\_id | Refers to the venue the fixture is played at | integer / null | | name | Represents the name of the participants | string / null | | starting\_at | Datetime object representing the start time | date / null | | result\_info | Represents the final result info | string / null | | leg | Represents the leg of the fixture | string | | details | Represents details about the fixture | string / null | | length | Length of the fixture (minutes) | integer / null | | {% endtab %} | | | | {% endtabs %} | | | {% tabs %} {% tab title="Query Parameters" %}

Name	Required?	Description
`api_token`	YES Another option is to provide the API token in the header.	Your unique API token. Ex. ?api_token=YOUR_TOKEN
`include`	NO	Enrich the API response with more data by using includes. Ex. &include=participants;events
`select`	NO	Select specific fields on the base entity. Read how to select fields in our tutorial.
`sortBy`	NO	Order by specific fields on the base entity. For more information check out this page.
`filters`	NO	Filter the API response on multiple related entities. There are static filters and dynamic filters. Please find the possibilities in the Static and Dynamic Filter tab.
`locale`	NO	Translate name fields of the API Response in your selected language. Find more information and which languages are available on our translations page.

Static Filters	Available on Entity	Description	Example
`participantSearch`	Fixture	Filter on the matches of specific participants.	`&include=participants&filters=participantSearch:Celtic`
`todayDate`	Fixture	Filter all fixtures to find only the fixtures of today.	`&filters=todayDate`
`venues`	Fixture	Find all fixtures that are played in a specific venue.	`&include=venue&filters=venues:venueIDs` `&include=venue&filters=venues:10,12`
`Deleted`	Fixture	Filter on deleted fixtures only. This filter helps to keep your database in sync.	`&filters=Deleted`
`markets`	Odds	Filter the odds on a selection of markets separated by a comma.	`&include=odds&filters=markets:marketIDs` `&include=odds&filters=markets:12,14`
`bookmakers`	Odds	Filter the odds on a selection of bookmakers separated by a comma. (e.g: 2,14).	`&include=odds&filters=bookmakers:bookmakerIDs` `&include=odds&filters=bookmakers:2,14`
`WinningOdds`	Odds	Filter all winning odds.	`&include=odds&filters=WinningOdds`

{% endtab %} {% tab title="Dynamic Filters" %} The **dynamic filters** are based on entities and includes. Each dynamic filter uses an entity to filter on and one entity to apply the filter to. Below is an example with an explanation of how filters are set up. For more information, please look at our[ Filters page](/v3/api/request-options/filtering). {% hint style="info" %} Using an include? Check their respective filters on their entity page. For example if you use `&include=participants` you can apply [team-related filters](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#team). {% endhint %}

Dynamic Filters	Available on Entity	Description	Examples
`types`	Statistics, Events, Lineup, and way more. Check this endpoint for all possibilities.	Filter the statistics, events and more on a selection of type ids separated by a comma.	`&include=statistics.type&filters=fixturestatisticTypes:TypeIDs` `&include=statistics.type&filters=fixturestatisticTypes:42,49` `&include=events&filters=eventTypes:14` `&include=lineups.details.type&filters=lineupdetailTypes:118`
`states`	Fixtures Check this endpoint for all possibilities.	Filter the states of fixtures separated by a comma.	`&include=state&filters=fixtureStates:StateIDs` `&include=state&filters=fixtureStates:1`
`leagues`	Fixtures, Seasons, Standings, and way more. Check this endpoint for all possibilities.	Filter the fixtures based on leagues and their rounds.	`&filters=fixtureLeagues:leagueIDs` `&filters=fixtureLeagues:501,271`
`groups`	Fixtures, Standing, and more. Check this endpoint for all possibilities.	Filter the fixtures based on groups. Get their fixtures and standings.	`&include=group&filters=fixtureGroups:groupIDs` `&include=group&filters=fixtureGroups:246691`
`countries`	Coaches, Leagues, Players, Teams, and way more. Check this endpoint for all possibilities.	Filter the coaches, leagues, players and more based on countries.	`&include=coaches&filters=coachCountries:CountryIDs` `&include=coaches&filters=coachCountries:1161`
`seasons`	Statistics (players, team, coaches, referees), Standings, and way more. Check this endpoint for all possibilities.	Filter statistics, standings and topscorers based on seasons.	`&include=season.statistics&filters=seasonStatisticTypes:TypeIDs` `&include=season.statistics&filters=seasonStatisticTypes:52`

{% endtab %} {% endtabs %} ### **Filters** More information on how to use filters can be found on our tutorials on how to [filter](https://docs.sportmonks.com/football2/api/request-options/filtering). If you want more information on which filters to use you can check out the following [endpoint](/v3/core-api/endpoints/filters/get-all-entity-filters): {% hint style="info" %} ```javascript https://api.sportmonks.com/v3/my/filters/entity?api_token=YOUR_TOKEN ``` {% endhint %} ### Pagination NO ### Include depth You can use a total of `3` nested includes on this endpoint ### Include options [`sport`](https://docs.sportmonks.com/v3/core-api/) [`round`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#round) [`stage`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#stage) [`group`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#group) [`aggregate`](/v3/endpoints-and-entities/entities/fixture#aggregate) [`league`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#league) [`season`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season)[`coaches`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#coach) [`tvStations`](/v3/endpoints-and-entities/entities/other#tvstation) [`venue`](/v3/endpoints-and-entities/entities/other#venue) [`state`](/v3/endpoints-and-entities/entities/other#state) [`weatherReport`](/v3/endpoints-and-entities/entities/other#weatherreport) [`lineups`](/v3/endpoints-and-entities/entities/fixture#lineup) [`events`](/v3/endpoints-and-entities/entities/fixture#event) [`timeline`](/v3/endpoints-and-entities/entities/fixture#event) [`comments`](/v3/endpoints-and-entities/entities/other#commentary) [`trends`](/v3/endpoints-and-entities/entities/statistic#trend) [`statistics`](/v3/endpoints-and-entities/entities/statistic#fixturestatistic) [`periods`](/v3/endpoints-and-entities/entities/fixture#period) [`participants` ](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#team)[`odds`](/v3/endpoints-and-entities/entities/odd-and-prediction#odd) [`premiumOdds`](https://docs.sportmonks.com/football/endpoints-and-entities/entities/odd-and-prediction#premium-odd)[`inplayOdds`](/v3/endpoints-and-entities/entities/odd-and-prediction#inplayodd) [`prematchNews`](/v3/endpoints-and-entities/entities/other#news) [`metadata`](/v3/endpoints-and-entities/entities/other#metadata) [`sidelined`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#sidelined)[`predictions`](/v3/endpoints-and-entities/entities/odd-and-prediction#prediction-valuebet) [`referees`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#referees) [`formations`](/v3/endpoints-and-entities/entities/fixture#formation) [`ballCoordinates`](/v3/endpoints-and-entities/entities/fixture#ballcoordinate) [`scores`](/v3/endpoints-and-entities/entities/fixture#score) [`xGFixture`](/v3/endpoints-and-entities/entities/expected) [`pressure`](/v3/tutorials-and-guides/tutorials/includes/pressure-index) `expectedLineups` `predictedLineups` `matchfacts` `AIOverviews` ### **Related Entities:** Get an overview and explanation of all the fields returned in the API response. The related entities for the fixtures endpoints are: * [Fixture](/v3/endpoints-and-entities/entities/fixture#fixture) ### Postman We also offer detailed postman documentation with examples and a complete up-to-date version of all our endpoints. Below is a button that lets your fork the collection or import it. \ [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316?action=collection%2Ffork\&collection-url=entityId%3D11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316%26entityType%3Dcollection%26workspaceId%3D17c720d0-d97b-42a9-9ea7-23260ed53ddf) ### Code Example {% tabs %} {% tab title="Ruby" %} ```ruby require "uri" require "net/http" url = URI("https://api.sportmonks.com/v3/football/fixtures/multi/{IDs}?api_token=YOUR_TOKEN") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Get.new(url) response = https.request(request) puts response.read_body ``` {% endtab %} {% tab title="Python" %} ```python import http.client conn = http.client.HTTPSConnection("api.sportmonks.com") payload = '' headers = {} conn.request("GET", "/v3/football/fixtures/multi/{IDs}?api_token=YOUR_TOKEN", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) ``` {% endtab %} {% tab title="PHP" %} ```php 'https://api.sportmonks.com/v3/football/fixtures/multi/{IDs}?api_token=YOUR_TOKEN', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', )); $response = curl_exec($curl); curl_close($curl); echo $respons ``` {% endtab %} {% tab title="Java" %} ```java OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://api.sportmonks.com/v3/football/fixtures/multi/{IDs}?api_token=YOUR_TOKEN") .method("GET", null) .build(); Response response = client.newCall(request).execute(); ``` {% endtab %} {% tab title="Node.js" %} ``` var unirest = require('unirest'); var req = unirest('GET', 'https://api.sportmonks.com/v3/football/fixtures/multi/{IDs}?api_token=YOUR_TOKEN') .end(function (res) { if (res.error) throw new Error(res.error); console.log(res.raw_body); }); ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://api.sportmonks.com/v3/football/fixtures/multi/{IDs}?api_token=YOUR_TOKEN" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %} # GET Fixtures by Date Returns the fixtures from your requested date. All you have to do is parse the date in YYYY-MM-DD format. {% tabs %} {% tab title="Base URL" %} ```javascript https://api.sportmonks.com/v3/football/fixtures/date/{date} ``` {% endtab %} {% tab title="Example Response" %} ```json { "data": [ { "id": 19146700, "sport_id": 1, "league_id": 501, "season_id": 23690, "stage_id": 77471570, "group_id": null, "aggregate_id": null, "round_id": 340573, "state_id": 5, "venue_id": 8879, "name": "St. Mirren vs Hibernian", "starting_at": "2024-08-04 14:00:00", "result_info": "St. Mirren won after full-time.", "leg": "1/1", "details": null, "length": 90, "placeholder": false, "has_odds": true, "has_premium_odds": true, "starting_at_timestamp": 1722780000 }, { "id": 19146701, "sport_id": 1, "league_id": 501, "season_id": 23690, "stage_id": 77471570, "group_id": null, "aggregate_id": null, "round_id": 340573, "state_id": 5, "venue_id": 8909, "name": "Celtic vs Kilmarnock", "starting_at": "2024-08-04 15:30:00", "result_info": "Celtic won after full-time.", "leg": "1/1", "details": null, "length": 90, "placeholder": false, "has_odds": true, "has_premium_odds": true, "starting_at_timestamp": 1722785400 } ``` {% endtab %} {% tab title="Field Description" %} | Field | Description | Type | | ------------- | ------------------------------------------------ | -------------- | | id | Refers the unique id of the fixture | integer | | sport\_id | Refers to the sport the fixture is played at | integer | | league\_id | Refers to the league the fixture is played in | integer | | season\_id | Refers to the seasons the fixture is played in | integer | | stage\_id | Refers to the stage the fixture is played in | integer | | group\_id | Refers to the group the fixture is played in | integer / null | | aggregate\_id | Refers to the aggregate the fixture is played at | integer / null | | state\_id | Refers to the state the fixture is played at | integer | | round\_id | Refers to the round the fixture is played at | integer / null | | state\_id | Refers to the state the fixture is played at | integer | | venue\_id | Refers to the venue the fixture is played at | integer / null | | name | Represents the name of the participants | string / null | | starting\_at | Datetime object representing the start time | date / null | | result\_info | Represents the final result info | string / null | | leg | Represents the leg of the fixture | string | | details | Represents details about the fixture | string / null | | length | Length of the fixture (minutes) | integer / null | | {% endtab %} | | | | {% endtabs %} | | | {% tabs %} {% tab title="Query Parameters" %}

Name	Required?	Description
`api_token`	YES Another option is to provide the API token in the header.	Your unique API token. Ex. ?api_token=YOUR_TOKEN
`include`	NO	Enrich the API response with more data by using includes. Ex. &include=participants;events
`select`	NO	Select specific fields on the base entity. Read how to select fields in our tutorial.
`sortBy`	NO	Order by specific fields on the base entity. For more information check out this page.
`filters`	NO	Filter the API response on multiple related entities. There are static filters and dynamic filters. Please find the possibilities in the Static and Dynamic Filter tab.
`locale`	NO	Translate name fields of the API Response in your selected language. Find more information and which languages are available on our translations page.

Static Filters	Available on Entity	Description	Example
`participantSearch`	Fixture	Filter on the matches of specific participants.	`&include=participants&filters=participantSearch:Celtic`
`todayDate`	Fixture	Filter all fixtures to find only the fixtures of today.	`&filters=todayDate`
`venues`	Fixture	Find all fixtures that are played in a specific venue.	`&include=venue&filters=venues:venueIDs` `&include=venue&filters=venues:10,12`
`Deleted`	Fixture	Filter on deleted fixtures only. This filter helps to keep your database in sync.	`&filters=Deleted`
`markets`	Odds	Filter the odds on a selection of markets separated by a comma.	`&include=odds&filters=markets:marketIDs` `&include=odds&filters=markets:12,14`
`bookmakers`	Odds	Filter the odds on a selection of bookmakers separated by a comma. (e.g: 2,14).	`&include=odds&filters=bookmakers:bookmakerIDs` `&include=odds&filters=bookmakers:2,14`
`WinningOdds`	Odds	Filter all winning odds.	`&include=odds&filters=WinningOdds`

{% endtab %} {% tab title="Dynamic Filters" %} The **dynamic filters** are based on entities and includes. Each dynamic filter uses an entity to filter on and one entity to apply the filter to. Below is an example with an explanation of how filters are set up. For more information, please look at our[ Filters page](/v3/api/request-options/filtering). {% hint style="info" %} Using an include? Check their respective filters on their entity page. For example if you use `&include=participants` you can apply [team-related filters](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#team). {% endhint %}

Dynamic Filters	Available on Entity	Description	Examples
`types`	Statistics, Events, Lineup, and way more. Check this endpoint for all possibilities.	Filter the statistics, events and more on a selection of type ids separated by a comma.	`&include=statistics.type&filters=fixturestatisticTypes:TypeIDs` `&include=statistics.type&filters=fixturestatisticTypes:42,49` `&include=events&filters=eventTypes:14` `&include=lineups.details.type&filters=lineupdetailTypes:118`
`states`	Fixtures Check this endpoint for all possibilities.	Filter the states of fixtures separated by a comma.	`&include=state&filters=fixtureStates:StateIDs` `&include=state&filters=fixtureStates:1`
`leagues`	Fixtures, Seasons, Standings, and way more. Check this endpoint for all possibilities.	Filter the fixtures based on leagues and their rounds.	`&filters=fixtureLeagues:leagueIDs` `&filters=fixtureLeagues:501,271`
`groups`	Fixtures, Standing, and more. Check this endpoint for all possibilities.	Filter the fixtures based on groups. Get their fixtures and standings.	`&include=group&filters=fixtureGroups:groupIDs` `&include=group&filters=fixtureGroups:246691`
`countries`	Coaches, Leagues, Players, Teams, and way more. Check this endpoint for all possibilities.	Filter the coaches, leagues, players and more based on countries.	`&include=coaches&filters=coachCountries:CountryIDs` `&include=coaches&filters=coachCountries:1161`
`seasons`	Statistics (players, team, coaches, referees), Standings, and way more. Check this endpoint for all possibilities.	Filter statistics, standings and topscorers based on seasons.	`&include=season.statistics&filters=seasonStatisticTypes:TypeIDs` `&include=season.statistics&filters=seasonStatisticTypes:52`

Parameter	Required	Description	Example
`order`	No	Returns fixtures ordered by starting_at (`asc` or `desc`). Defaults to asc	&order=desc
`per_page`	No	The amount of results to return per page (max 50.). Defaults to 25.	&per_page=30
`page`	No	You can paginate using the `has_more` parameter to determine if you can still propagate through the results.	&page=2

### Include depth You can use a total of `3` nested includes on this endpoint ### Include options [`sport`](https://docs.sportmonks.com/v3/core-api/) [`round`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#round) [`stage`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#stage) [`group`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#group) [`aggregate`](/v3/endpoints-and-entities/entities/fixture#aggregate) [`league`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#league) [`season`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season)[`coaches`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#coach) [`tvStations`](/v3/endpoints-and-entities/entities/other#tvstation) [`venue`](/v3/endpoints-and-entities/entities/other#venue) [`state`](/v3/endpoints-and-entities/entities/other#state) [`weatherReport`](/v3/endpoints-and-entities/entities/other#weatherreport) [`lineups`](/v3/endpoints-and-entities/entities/fixture#lineup) [`events`](/v3/endpoints-and-entities/entities/fixture#event) [`timeline`](/v3/endpoints-and-entities/entities/fixture#event) [`comments`](/v3/endpoints-and-entities/entities/other#commentary) [`trends`](/v3/endpoints-and-entities/entities/statistic#trend) [`statistics`](/v3/endpoints-and-entities/entities/statistic#fixturestatistic) [`periods`](/v3/endpoints-and-entities/entities/fixture#period) [`participants` ](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#team)[`odds`](/v3/endpoints-and-entities/entities/odd-and-prediction#odd) [`premiumOdds`](https://docs.sportmonks.com/football/endpoints-and-entities/entities/odd-and-prediction#premium-odd)[`inplayOdds`](/v3/endpoints-and-entities/entities/odd-and-prediction#inplayodd) [`prematchNews`](/v3/endpoints-and-entities/entities/other#news) [`postmatchNews`](/v3/endpoints-and-entities/entities/other#news) [`metadata`](/v3/endpoints-and-entities/entities/other#metadata) [`sidelined`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#sidelined)[`predictions`](/v3/endpoints-and-entities/entities/odd-and-prediction#prediction-valuebet) [`referees`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#referees) [`formations`](/v3/endpoints-and-entities/entities/fixture#formation) [`ballCoordinates`](/v3/endpoints-and-entities/entities/fixture#ballcoordinate) [`scores`](/v3/endpoints-and-entities/entities/fixture#score) [`xGFixture`](/v3/endpoints-and-entities/entities/expected) [`pressure`](/v3/tutorials-and-guides/tutorials/includes/pressure-index) `expectedLineups` `predictedLineups` `matchfacts` `AIOverviews` ### **Related Entities:** Get an overview and explanation of all the fields returned in the API response. The related entities for the fixtures endpoints are: * [Fixture](/v3/endpoints-and-entities/entities/fixture#fixture) ### Postman We also offer detailed postman documentation with examples and a complete up-to-date version of all our endpoints. Below is a button that lets your fork the collection or import it. \ [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316?action=collection%2Ffork\&collection-url=entityId%3D11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316%26entityType%3Dcollection%26workspaceId%3D17c720d0-d97b-42a9-9ea7-23260ed53ddf) ### Code Example {% tabs %} {% tab title="Ruby" %} ```ruby require "uri" require "net/http" url = URI("https://api.sportmonks.com/v3/football/fixtures/date/{date}?api_token=YOUR_TOKEN") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Get.new(url) response = https.request(request) puts response.read_body ``` {% endtab %} {% tab title="Python" %} ```python import http.client conn = http.client.HTTPSConnection("api.sportmonks.com") payload = '' headers = {} conn.request("GET", "/v3/football/fixtures/date/{date}?api_token=YOUR_TOKEN", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) ``` {% endtab %} {% tab title="PHP" %} ```php 'https://api.sportmonks.com/v3/football/fixtures/date/{date}?api_token=YOUR_TOKEN', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', )); $response = curl_exec($curl); curl_close($curl); echo $respons ``` {% endtab %} {% tab title="Java" %} ```java OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://api.sportmonks.com/v3/football/fixtures/date/{date}?api_token=YOUR_TOKEN") .method("GET", null) .build(); Response response = client.newCall(request).execute(); ``` {% endtab %} {% tab title="Node.js" %} ``` var unirest = require('unirest'); var req = unirest('GET', 'https://api.sportmonks.com/v3/football/fixtures/date/{date}?api_token=YOUR_TOKEN') .end(function (res) { if (res.error) throw new Error(res.error); console.log(res.raw_body); }); ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://api.sportmonks.com/v3/football/fixtures/date/{date}?api_token=YOUR_TOKEN" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %} # GET Fixtures by Date Range Returns the fixtures from your requested date range. The maximum range is 100 days. All you have to do is parse the date in YYYY-MM-DD format. {% tabs %} {% tab title="Base URL" %} ```javascript https://api.sportmonks.com/v3/football/fixtures/between/{start_date}/{end_date} ``` {% endtab %} {% tab title="Example Response" %} ```json { "data": [ { "id": 19146700, "sport_id": 1, "league_id": 501, "season_id": 23690, "stage_id": 77471570, "group_id": null, "aggregate_id": null, "round_id": 340573, "state_id": 5, "venue_id": 8879, "name": "St. Mirren vs Hibernian", "starting_at": "2024-08-04 14:00:00", "result_info": "St. Mirren won after full-time.", "leg": "1/1", "details": null, "length": 90, "placeholder": false, "has_odds": true, "has_premium_odds": true, "starting_at_timestamp": 1722780000 }, { "id": 19146701, "sport_id": 1, "league_id": 501, "season_id": 23690, "stage_id": 77471570, "group_id": null, "aggregate_id": null, "round_id": 340573, "state_id": 5, "venue_id": 8909, "name": "Celtic vs Kilmarnock", "starting_at": "2024-08-04 15:30:00", "result_info": "Celtic won after full-time.", "leg": "1/1", "details": null, "length": 90, "placeholder": false, "has_odds": true, "has_premium_odds": true, "starting_at_timestamp": 1722785400 } ``` {% endtab %} {% tab title="Field Description" %} | Field | Description | Type | | ------------- | ------------------------------------------------ | -------------- | | id | Refers the unique id of the fixture | integer | | sport\_id | Refers to the sport the fixture is played at | integer | | league\_id | Refers to the league the fixture is played in | integer | | season\_id | Refers to the seasons the fixture is played in | integer | | stage\_id | Refers to the stage the fixture is played in | integer | | group\_id | Refers to the group the fixture is played in | integer / null | | aggregate\_id | Refers to the aggregate the fixture is played at | integer / null | | state\_id | Refers to the state the fixture is played at | integer | | round\_id | Refers to the round the fixture is played at | integer / null | | state\_id | Refers to the state the fixture is played at | integer | | venue\_id | Refers to the venue the fixture is played at | integer / null | | name | Represents the name of the participants | string / null | | starting\_at | Datetime object representing the start time | date / null | | result\_info | Represents the final result info | string / null | | leg | Represents the leg of the fixture | string | | details | Represents details about the fixture | string / null | | length | Length of the fixture (minutes) | integer / null | | {% endtab %} | | | | {% endtabs %} | | | {% tabs %} {% tab title="Query Parameters" %}

Name	Required?	Description
`api_token`	YES Another option is to provide the API token in the header.	Your unique API token. Ex. ?api_token=YOUR_TOKEN
`include`	NO	Enrich the API response with more data by using includes. Ex. &include=participants;events
`select`	NO	Select specific fields on the base entity. Read how to select fields in our tutorial.
`sortBy`	NO	Order by specific fields on the base entity. For more information check out this page.
`filters`	NO	Filter the API response on multiple related entities. There are static filters and dynamic filters. Please find the possibilities in the Static and Dynamic Filter tab.
`locale`	NO	Translate name fields of the API Response in your selected language. Find more information and which languages are available on our translations page.

Static Filters	Available on Entity	Description	Example
`participantSearch`	Fixture	Filter on the matches of specific participants.	`&include=participants&filters=participantSearch:Celtic`
`todayDate`	Fixture	Filter all fixtures to find only the fixtures of today.	`&filters=todayDate`
`venues`	Fixture	Find all fixtures that are played in a specific venue.	`&include=venue&filters=venues:venueIDs` `&include=venue&filters=venues:10,12`
`Deleted`	Fixture	Filter on deleted fixtures only. This filter helps to keep your database in sync.	`&filters=Deleted`
`markets`	Odds	Filter the odds on a selection of markets separated by a comma.	`&include=odds&filters=markets:marketIDs` `&include=odds&filters=markets:12,14`
`bookmakers`	Odds	Filter the odds on a selection of bookmakers separated by a comma. (e.g: 2,14).	`&include=odds&filters=bookmakers:bookmakerIDs` `&include=odds&filters=bookmakers:2,14`
`WinningOdds`	Odds	Filter all winning odds.	`&include=odds&filters=WinningOdds`

{% endtab %} {% tab title="Dynamic Filters" %} The **dynamic filters** are based on entities and includes. Each dynamic filter uses an entity to filter on and one entity to apply the filter to. Below is an example with an explanation of how filters are set up. For more information, please look at our[ Filters page](/v3/api/request-options/filtering). {% hint style="info" %} Using an include? Check their respective filters on their entity page. For example if you use `&include=participants` you can apply [team-related filters](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#team). {% endhint %}

Dynamic Filters	Available on Entity	Description	Examples
`types`	Statistics, Events, Lineup, and way more. Check this endpoint for all possibilities.	Filter the statistics, events and more on a selection of type ids separated by a comma.	`&include=statistics.type&filters=fixturestatisticTypes:TypeIDs` `&include=statistics.type&filters=fixturestatisticTypes:42,49` `&include=events&filters=eventTypes:14` `&include=lineups.details.type&filters=lineupdetailTypes:118`
`states`	Fixtures Check this endpoint for all possibilities.	Filter the states of fixtures separated by a comma.	`&include=state&filters=fixtureStates:StateIDs` `&include=state&filters=fixtureStates:1`
`leagues`	Fixtures, Seasons, Standings, and way more. Check this endpoint for all possibilities.	Filter the fixtures based on leagues and their rounds.	`&filters=fixtureLeagues:leagueIDs` `&filters=fixtureLeagues:501,271`
`groups`	Fixtures, Standing, and more. Check this endpoint for all possibilities.	Filter the fixtures based on groups. Get their fixtures and standings.	`&include=group&filters=fixtureGroups:groupIDs` `&include=group&filters=fixtureGroups:246691`
`countries`	Coaches, Leagues, Players, Teams, and way more. Check this endpoint for all possibilities.	Filter the coaches, leagues, players and more based on countries.	`&include=coaches&filters=coachCountries:CountryIDs` `&include=coaches&filters=coachCountries:1161`
`seasons`	Statistics (players, team, coaches, referees), Standings, and way more. Check this endpoint for all possibilities.	Filter statistics, standings and topscorers based on seasons.	`&include=season.statistics&filters=seasonStatisticTypes:TypeIDs` `&include=season.statistics&filters=seasonStatisticTypes:52`

{% endtab %} {% endtabs %} {% hint style="warning" %} The maximum date range for this endpoint is 100 days. {% endhint %} ### **Filters** More information on how to use filters can be found on our tutorials on how to [filter](https://docs.sportmonks.com/football2/api/request-options/filtering). If you want more information on which filters to use you can check out the following [endpoint](/v3/core-api/endpoints/filters/get-all-entity-filters): {% hint style="info" %} ```javascript https://api.sportmonks.com/v3/my/filters/entity?api_token=YOUR_TOKEN ``` {% endhint %} ### Pagination YES ### Parameters

Parameter	Required	Description	Example
`order`	No	Returns fixtures ordered by starting_at (`asc` or `desc`). Defaults to asc	&order=desc
`per_page`	No	The amount of results to return per page (max 50.). Defaults to 25.	&per_page=30
`page`	No	You can paginate using the `has_more` parameter to determine if you can still propagate through the results.	&page=2

### Include depth You can use a total of `3` nested includes on this endpoint ### Include options [`sport`](https://docs.sportmonks.com/v3/core-api/) [`round`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#round) [`stage`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#stage) [`group`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#group) [`aggregate`](/v3/endpoints-and-entities/entities/fixture#aggregate) [`league`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#league) [`season`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season)[`coaches`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#coach) [`tvStations`](/v3/endpoints-and-entities/entities/other#tvstation) [`venue`](/v3/endpoints-and-entities/entities/other#venue) [`state`](/v3/endpoints-and-entities/entities/other#state) [`weatherReport`](/v3/endpoints-and-entities/entities/other#weatherreport) [`lineups`](/v3/endpoints-and-entities/entities/fixture#lineup) [`events`](/v3/endpoints-and-entities/entities/fixture#event) [`timeline`](/v3/endpoints-and-entities/entities/fixture#event) [`comments`](/v3/endpoints-and-entities/entities/other#commentary) [`trends`](/v3/endpoints-and-entities/entities/statistic#trend) [`statistics`](/v3/endpoints-and-entities/entities/statistic#fixturestatistic) [`periods`](/v3/endpoints-and-entities/entities/fixture#period) [`participants` ](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#team)[`odds`](/v3/endpoints-and-entities/entities/odd-and-prediction#odd) [`premiumOdds`](https://docs.sportmonks.com/football/endpoints-and-entities/entities/odd-and-prediction#premium-odd)[`inplayOdds`](/v3/endpoints-and-entities/entities/odd-and-prediction#inplayodd) [`prematchNews`](/v3/endpoints-and-entities/entities/other#news) [`postmatchNews`](/v3/endpoints-and-entities/entities/other#news) [`metadata`](/v3/endpoints-and-entities/entities/other#metadata) [`sidelined`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#sidelined)[`predictions`](/v3/endpoints-and-entities/entities/odd-and-prediction#prediction-valuebet) [`referees`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#referees) [`formations`](/v3/endpoints-and-entities/entities/fixture#formation) [`ballCoordinates`](/v3/endpoints-and-entities/entities/fixture#ballcoordinate) [`scores`](/v3/endpoints-and-entities/entities/fixture#score) [`xGFixture`](/v3/endpoints-and-entities/entities/expected) [`pressure`](/v3/tutorials-and-guides/tutorials/includes/pressure-index) `expectedLineups` `predictedLineups` `matchfacts` `AIOverviews` ### **Related Entities:** Get an overview and explanation of all the fields returned in the API response. The related entities for the fixtures endpoints are: * [Fixture](/v3/endpoints-and-entities/entities/fixture#fixture) ### Postman We also offer detailed postman documentation with examples and a complete up-to-date version of all our endpoints. Below is a button that lets your fork the collection or import it. \ [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316?action=collection%2Ffork\&collection-url=entityId%3D11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316%26entityType%3Dcollection%26workspaceId%3D17c720d0-d97b-42a9-9ea7-23260ed53ddf) ### Code Example {% tabs %} {% tab title="Ruby" %} ```ruby require "uri" require "net/http" url = URI("https://api.sportmonks.com/v3/football/fixtures/between/{start_date}/{end_date}?api_token=YOUR_TOKEN") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Get.new(url) response = https.request(request) puts response.read_body ``` {% endtab %} {% tab title="Python" %} ```python import http.client conn = http.client.HTTPSConnection("api.sportmonks.com") payload = '' headers = {} conn.request("GET", "/v3/football/fixtures/between/{start_date}/{end_date}}?api_token=YOUR_TOKEN", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) ``` {% endtab %} {% tab title="PHP" %} ```php 'https://api.sportmonks.com/v3/football/fixtures/between/{start_date}/{end_date}?api_token=YOUR_TOKEN', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', )); $response = curl_exec($curl); curl_close($curl); echo $respons ``` {% endtab %} {% tab title="Java" %} ```java OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://api.sportmonks.com/v3/football/fixtures/between/{start_date}/{end_date}?api_token=YOUR_TOKEN") .method("GET", null) .build(); Response response = client.newCall(request).execute(); ``` {% endtab %} {% tab title="Node.js" %} ``` var unirest = require('unirest'); var req = unirest('GET', 'https://api.sportmonks.com/v3/football/fixtures/between/{start_date}/{end_date}?api_token=YOUR_TOKEN') .end(function (res) { if (res.error) throw new Error(res.error); console.log(res.raw_body); }); ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://api.sportmonks.com/v3/football/fixtures/between/{start_date}/{end_date}?api_token=YOUR_TOKEN" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %} # GET Fixtures by Date Range for Team Returns the fixtures from your requested date range for your team. All you have to do is parse the date in YYYY-MM-DD format and add the team ID. {% tabs %} {% tab title="Base URL" %} ```javascript https://api.sportmonks.com/v3/football/fixtures/between/{start_date}/{end_date}/{team_id} ``` {% endtab %} {% tab title="Example Response" %} ```json { "data": [ { "id": 19116491, "sport_id": 1, "league_id": 501, "season_id": 21787, "stage_id": 77464482, "group_id": 249096, "aggregate_id": null, "round_id": 337538, "state_id": 5, "venue_id": 8914, "name": "Rangers vs Dundee", "starting_at": "2024-05-14 18:30:00", "result_info": "Rangers won after full-time.", "leg": "1/1", "details": null, "length": 90, "placeholder": false, "has_odds": true, "has_premium_odds": true, "starting_at_timestamp": 1715711400 }, { "id": 19116496, "sport_id": 1, "league_id": 501, "season_id": 21787, "stage_id": 77464482, "group_id": 249096, "aggregate_id": null, "round_id": 337539, "state_id": 5, "venue_id": 336296, "name": "Hearts vs Rangers", "starting_at": "2024-05-18 11:30:00", "result_info": "Game ended in draw.", "leg": "1/1", "details": null, "length": 90, "placeholder": false, "has_odds": true, "has_premium_odds": true, "starting_at_timestamp": 1716031800 } ``` {% endtab %} {% tab title="Field Description" %} | Field | Description | Type | | ------------- | ------------------------------------------------ | -------------- | | id | Refers the unique id of the fixture | integer | | sport\_id | Refers to the sport the fixture is played at | integer | | league\_id | Refers to the league the fixture is played in | integer | | season\_id | Refers to the seasons the fixture is played in | integer | | stage\_id | Refers to the stage the fixture is played in | integer | | group\_id | Refers to the group the fixture is played in | integer / null | | aggregate\_id | Refers to the aggregate the fixture is played at | integer / null | | state\_id | Refers to the state the fixture is played at | integer | | round\_id | Refers to the round the fixture is played at | integer / null | | state\_id | Refers to the state the fixture is played at | integer | | venue\_id | Refers to the venue the fixture is played at | integer / null | | name | Represents the name of the participants | string / null | | starting\_at | Datetime object representing the start time | date / null | | result\_info | Represents the final result info | string / null | | leg | Represents the leg of the fixture | string | | details | Represents details about the fixture | string / null | | length | Length of the fixture (minutes) | integer / null | | {% endtab %} | | | | {% endtabs %} | | | {% tabs %} {% tab title="Query Parameters" %}

Name	Required?	Description
`api_token`	YES Another option is to provide the API token in the header.	Your unique API token. Ex. ?api_token=YOUR_TOKEN
`include`	NO	Enrich the API response with more data by using includes. Ex. &include=participants;events
`select`	NO	Select specific fields on the base entity. Read how to select fields in our tutorial.
`sortBy`	NO	Order by specific fields on the base entity. For more information check out this page.
`filters`	NO	Filter the API response on multiple related entities. There are static filters and dynamic filters. Please find the possibilities in the Static and Dynamic Filter tab.
`locale`	NO	Translate name fields of the API Response in your selected language. Find more information and which languages are available on our translations page.

Static Filters	Available on Entity	Description	Example
`participantSearch`	Fixture	Filter on the matches of specific participants.	`&include=participants&filters=participantSearch:Celtic`
`todayDate`	Fixture	Filter all fixtures to find only the fixtures of today.	`&filters=todayDate`
`venues`	Fixture	Find all fixtures that are played in a specific venue.	`&include=venue&filters=venues:venueIDs` `&include=venue&filters=venues:10,12`
`Deleted`	Fixture	Filter on deleted fixtures only. This filter helps to keep your database in sync.	`&filters=Deleted`
`markets`	Odds	Filter the odds on a selection of markets separated by a comma.	`&include=odds&filters=markets:marketIDs` `&include=odds&filters=markets:12,14`
`bookmakers`	Odds	Filter the odds on a selection of bookmakers separated by a comma. (e.g: 2,14).	`&include=odds&filters=bookmakers:bookmakerIDs` `&include=odds&filters=bookmakers:2,14`
`WinningOdds`	Odds	Filter all winning odds.	`&include=odds&filters=WinningOdds`

{% endtab %} {% tab title="Dynamic Filters" %} The **dynamic filters** are based on entities and includes. Each dynamic filter uses an entity to filter on and one entity to apply the filter to. Below is an example with an explanation of how filters are set up. For more information, please look at our[ Filters page](/v3/api/request-options/filtering). {% hint style="info" %} Using an include? Check their respective filters on their entity page. For example if you use `&include=participants` you can apply [team-related filters](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#team). {% endhint %}

Dynamic Filters	Available on Entity	Description	Examples
`types`	Statistics, Events, Lineup, and way more. Check this endpoint for all possibilities.	Filter the statistics, events and more on a selection of type ids separated by a comma.	`&include=statistics.type&filters=fixturestatisticTypes:TypeIDs` `&include=statistics.type&filters=fixturestatisticTypes:42,49` `&include=events&filters=eventTypes:14` `&include=lineups.details.type&filters=lineupdetailTypes:118`
`states`	Fixtures Check this endpoint for all possibilities.	Filter the states of fixtures separated by a comma.	`&include=state&filters=fixtureStates:StateIDs` `&include=state&filters=fixtureStates:1`
`leagues`	Fixtures, Seasons, Standings, and way more. Check this endpoint for all possibilities.	Filter the fixtures based on leagues and their rounds.	`&filters=fixtureLeagues:leagueIDs` `&filters=fixtureLeagues:501,271`
`groups`	Fixtures, Standing, and more. Check this endpoint for all possibilities.	Filter the fixtures based on groups. Get their fixtures and standings.	`&include=group&filters=fixtureGroups:groupIDs` `&include=group&filters=fixtureGroups:246691`
`countries`	Coaches, Leagues, Players, Teams, and way more. Check this endpoint for all possibilities.	Filter the coaches, leagues, players and more based on countries.	`&include=coaches&filters=coachCountries:CountryIDs` `&include=coaches&filters=coachCountries:1161`
`seasons`	Statistics (players, team, coaches, referees), Standings, and way more. Check this endpoint for all possibilities.	Filter statistics, standings and topscorers based on seasons.	`&include=season.statistics&filters=seasonStatisticTypes:TypeIDs` `&include=season.statistics&filters=seasonStatisticTypes:52`

Parameter	Required	Description	Example
`order`	No	Returns fixtures ordered by starting_at (`asc` or `desc`). Defaults to asc	&order=desc
`per_page`	No	The amount of results to return per page (max 50.). Defaults to 25.	&per_page=30
`page`	No	You can paginate using the `has_more` parameter to determine if you can still propagate through the results.	&page=2

### Include depth You can use a total of `3` nested includes on this endpoint ### Include options [`sport`](https://docs.sportmonks.com/v3/core-api/) [`round`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#round) [`stage`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#stage) [`group`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#group) [`aggregate`](/v3/endpoints-and-entities/entities/fixture#aggregate) [`league`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#league) [`season`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season)[`coaches`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#coach) [`tvStations`](/v3/endpoints-and-entities/entities/other#tvstation) [`venue`](/v3/endpoints-and-entities/entities/other#venue) [`state`](/v3/endpoints-and-entities/entities/other#state) [`weatherReport`](/v3/endpoints-and-entities/entities/other#weatherreport) [`lineups`](/v3/endpoints-and-entities/entities/fixture#lineup) [`events`](/v3/endpoints-and-entities/entities/fixture#event) [`timeline`](/v3/endpoints-and-entities/entities/fixture#event) [`comments`](/v3/endpoints-and-entities/entities/other#commentary) [`trends`](/v3/endpoints-and-entities/entities/statistic#trend) [`statistics`](/v3/endpoints-and-entities/entities/statistic#fixturestatistic) [`periods`](/v3/endpoints-and-entities/entities/fixture#period) [`participants` ](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#team)[`odds`](/v3/endpoints-and-entities/entities/odd-and-prediction#odd)[`premiumOdds`](https://docs.sportmonks.com/football/endpoints-and-entities/entities/odd-and-prediction#premium-odd) [`inplayOdds`](/v3/endpoints-and-entities/entities/odd-and-prediction#inplayodd) [`prematchNews`](/v3/endpoints-and-entities/entities/other#news) [`postmatchNews`](/v3/endpoints-and-entities/entities/other#news) [`metadata`](/v3/endpoints-and-entities/entities/other#metadata) [`sidelined`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#sidelined)[`predictions`](/v3/endpoints-and-entities/entities/odd-and-prediction#prediction-valuebet) [`referees`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#referees) [`formations`](/v3/endpoints-and-entities/entities/fixture#formation) [`ballCoordinates`](/v3/endpoints-and-entities/entities/fixture#ballcoordinate) [`scores`](/v3/endpoints-and-entities/entities/fixture#score) [`xGFixture`](/v3/endpoints-and-entities/entities/expected) [`pressure`](/v3/tutorials-and-guides/tutorials/includes/pressure-index) `expectedLineups` `predictedLineups` `matchfacts` `AIOverviews` ### **Related Entities:** Get an overview and explanation of all the fields returned in the API response. The related entities for the fixtures endpoints are: * [Fixture](/v3/endpoints-and-entities/entities/fixture#fixture) ### Code Example {% tabs %} {% tab title="Ruby" %} ```ruby require "uri" require "net/http" url = URI("https://api.sportmonks.com/v3/football/fixtures/between/{start_date}/{end_date}/{team_id}?api_token=YOUR_TOKEN") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Get.new(url) response = https.request(request) puts response.read_body ``` {% endtab %} {% tab title="Python" %} ```python import http.client conn = http.client.HTTPSConnection("api.sportmonks.com") payload = '' headers = {} conn.request("GET", "/v3/football/fixtures/between/{start_date}/{end_date}/{team_id}?api_token=YOUR_TOKEN", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) ``` {% endtab %} {% tab title="PHP" %} ```php 'https://api.sportmonks.com/v3/football/fixtures/between/{start_date}/{end_date}/{team_id}?api_token=YOUR_TOKEN', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', )); $response = curl_exec($curl); curl_close($curl); echo $respons ``` {% endtab %} {% tab title="Java" %} ```java OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://api.sportmonks.com/v3/football/fixtures/between/{start_date}/{end_date}/{team_id}?api_token=YOUR_TOKEN") .method("GET", null) .build(); Response response = client.newCall(request).execute(); ``` {% endtab %} {% tab title="Node.js" %} ``` var unirest = require('unirest'); var req = unirest('GET', 'https://api.sportmonks.com/v3/football/fixtures/between/{start_date}/{end_date}/{team_id}?api_token=YOUR_TOKEN') .end(function (res) { if (res.error) throw new Error(res.error); console.log(res.raw_body); }); ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://api.sportmonks.com/v3/football/fixtures/between/{start_date}/{end_date}/{team_id}?api_token=YOUR_TOKEN" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %} # GET Fixtures by Head To Head Returns the head to head fixtures of two teams you’ve requested. {% tabs %} {% tab title="Base URL" %} ```javascript https://api.sportmonks.com/v3/football/fixtures/head-to-head/{team_id_1}/{team_id2} ``` {% endtab %} {% tab title="Example Response" %} ```json { "id": 19146697, "sport_id": 1, "league_id": 501, "season_id": 23690, "stage_id": 77471570, "group_id": null, "aggregate_id": null, "round_id": 340573, "state_id": 5, "venue_id": 336296, "name": "Hearts vs Rangers", "starting_at": "2024-08-03 11:30:00", "result_info": "Game ended in draw.", "leg": "1/1", "details": null, "length": 90, "placeholder": false, "has_odds": true, "has_premium_odds": true, "starting_at_timestamp": 1722684600 }, { "id": 19116496, "sport_id": 1, "league_id": 501, "season_id": 21787, "stage_id": 77464482, "group_id": 249096, "aggregate_id": null, "round_id": 337539, "state_id": 5, "venue_id": 336296, "name": "Hearts vs Rangers", "starting_at": "2024-05-18 11:30:00", "result_info": "Game ended in draw.", "leg": "1/1", "details": null, "length": 90, "placeholder": false, "has_odds": true, "has_premium_odds": true, "starting_at_timestamp": 1716031800 }, ``` {% endtab %} {% tab title="Field Description" %} | Field | Description | Type | | ------------- | ------------------------------------------------ | -------------- | | id | Refers the unique id of the fixture | integer | | sport\_id | Refers to the sport the fixture is played at | integer | | league\_id | Refers to the league the fixture is played in | integer | | season\_id | Refers to the seasons the fixture is played in | integer | | stage\_id | Refers to the stage the fixture is played in | integer | | group\_id | Refers to the group the fixture is played in | integer / null | | aggregate\_id | Refers to the aggregate the fixture is played at | integer / null | | state\_id | Refers to the state the fixture is played at | integer | | round\_id | Refers to the round the fixture is played at | integer / null | | state\_id | Refers to the state the fixture is played at | integer | | venue\_id | Refers to the venue the fixture is played at | integer / null | | name | Represents the name of the participants | string / null | | starting\_at | Datetime object representing the start time | date / null | | result\_info | Represents the final result info | string / null | | leg | Represents the leg of the fixture | string | | details | Represents details about the fixture | string / null | | length | Length of the fixture (minutes) | integer / null | | {% endtab %} | | | | {% endtabs %} | | | {% tabs %} {% tab title="Query Parameters" %}

Name	Required?	Description
`api_token`	YES Another option is to provide the API token in the header.	Your unique API token. Ex. ?api_token=YOUR_TOKEN
`include`	NO	Enrich the API response with more data by using includes. Ex. &include=participants;events
`select`	NO	Select specific fields on the base entity. Read how to select fields in our tutorial.
`sortBy`	NO	Order by specific fields on the base entity. For more information check out this page.
`filters`	NO	Filter the API response on multiple related entities. There are static filters and dynamic filters. Please find the possibilities in the Static and Dynamic Filter tab.
`locale`	NO	Translate name fields of the API Response in your selected language. Find more information and which languages are available on our translations page.

Static Filters	Available on Entity	Description	Example
`participantSearch`	Fixture	Filter on the matches of specific participants.	`&include=participants&filters=participantSearch:Celtic`
`todayDate`	Fixture	Filter all fixtures to find only the fixtures of today.	`&filters=todayDate`
`venues`	Fixture	Find all fixtures that are played in a specific venue.	`&include=venue&filters=venues:venueIDs` `&include=venue&filters=venues:10,12`
`Deleted`	Fixture	Filter on deleted fixtures only. This filter helps to keep your database in sync.	`&filters=Deleted`
`markets`	Odds	Filter the odds on a selection of markets separated by a comma.	`&include=odds&filters=markets:marketIDs` `&include=odds&filters=markets:12,14`
`bookmakers`	Odds	Filter the odds on a selection of bookmakers separated by a comma. (e.g: 2,14).	`&include=odds&filters=bookmakers:bookmakerIDs` `&include=odds&filters=bookmakers:2,14`
`WinningOdds`	Odds	Filter all winning odds.	`&include=odds&filters=WinningOdds`

{% endtab %} {% tab title="Dynamic Filters" %} The **dynamic filters** are based on entities and includes. Each dynamic filter uses an entity to filter on and one entity to apply the filter to. Below is an example with an explanation of how filters are set up. For more information, please look at our[ Filters page](/v3/api/request-options/filtering). {% hint style="info" %} Using an include? Check their respective filters on their entity page. For example if you use `&include=participants` you can apply [team-related filters](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#team). {% endhint %}

Dynamic Filters	Available on Entity	Description	Examples
`types`	Statistics, Events, Lineup, and way more. Check this endpoint for all possibilities.	Filter the statistics, events and more on a selection of type ids separated by a comma.	`&include=statistics.type&filters=fixturestatisticTypes:TypeIDs` `&include=statistics.type&filters=fixturestatisticTypes:42,49` `&include=events&filters=eventTypes:14` `&include=lineups.details.type&filters=lineupdetailTypes:118`
`states`	Fixtures Check this endpoint for all possibilities.	Filter the states of fixtures separated by a comma.	`&include=state&filters=fixtureStates:StateIDs` `&include=state&filters=fixtureStates:1`
`leagues`	Fixtures, Seasons, Standings, and way more. Check this endpoint for all possibilities.	Filter the fixtures based on leagues and their rounds.	`&filters=fixtureLeagues:leagueIDs` `&filters=fixtureLeagues:501,271`
`groups`	Fixtures, Standing, and more. Check this endpoint for all possibilities.	Filter the fixtures based on groups. Get their fixtures and standings.	`&include=group&filters=fixtureGroups:groupIDs` `&include=group&filters=fixtureGroups:246691`
`countries`	Coaches, Leagues, Players, Teams, and way more. Check this endpoint for all possibilities.	Filter the coaches, leagues, players and more based on countries.	`&include=coaches&filters=coachCountries:CountryIDs` `&include=coaches&filters=coachCountries:1161`
`seasons`	Statistics (players, team, coaches, referees), Standings, and way more. Check this endpoint for all possibilities.	Filter statistics, standings and topscorers based on seasons.	`&include=season.statistics&filters=seasonStatisticTypes:TypeIDs` `&include=season.statistics&filters=seasonStatisticTypes:52`

{% endtab %} {% endtabs %} ### **Filters** More information on how to use filters can be found on our tutorials on how to [filter](https://docs.sportmonks.com/football2/api/request-options/filtering). If you want more information on which filters to use you can check out the following [endpoint](/v3/core-api/endpoints/filters/get-all-entity-filters): {% hint style="info" %} ```javascript https://api.sportmonks.com/v3/my/filters/entity?api_token=YOUR_TOKEN ``` {% endhint %} ### Pagination YES ### Include depth You can use a total of `3` nested includes on this endpoint ### Include options [`sport`](https://docs.sportmonks.com/v3/core-api/) [`round`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#round) [`stage`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#stage) [`group`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#group) [`aggregate`](/v3/endpoints-and-entities/entities/fixture#aggregate) [`league`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#league) [`season`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season)[`coaches`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#coach) [`tvStations`](/v3/endpoints-and-entities/entities/other#tvstation) [`venue`](/v3/endpoints-and-entities/entities/other#venue) [`state`](/v3/endpoints-and-entities/entities/other#state) [`weatherReport`](/v3/endpoints-and-entities/entities/other#weatherreport) [`lineups`](/v3/endpoints-and-entities/entities/fixture#lineup) [`events`](/v3/endpoints-and-entities/entities/fixture#event) [`timeline`](/v3/endpoints-and-entities/entities/fixture#event) [`comments`](/v3/endpoints-and-entities/entities/other#commentary) [`trends`](/v3/endpoints-and-entities/entities/statistic#trend) [`statistics`](/v3/endpoints-and-entities/entities/statistic#fixturestatistic) [`periods`](/v3/endpoints-and-entities/entities/fixture#period) [`participants` ](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#team)[`odds`](/v3/endpoints-and-entities/entities/odd-and-prediction#odd) [`premiumOdds`](https://docs.sportmonks.com/football/endpoints-and-entities/entities/odd-and-prediction#premium-odd)[`inplayOdds`](/v3/endpoints-and-entities/entities/odd-and-prediction#inplayodd) [`prematchNews`](/v3/endpoints-and-entities/entities/other#news) [`postmatchNews`](/v3/endpoints-and-entities/entities/other#news) [`metadata`](/v3/endpoints-and-entities/entities/other#metadata) [`sidelined`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#sidelined)[`predictions`](/v3/endpoints-and-entities/entities/odd-and-prediction#prediction-valuebet) [`referees`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#referees) [`formations`](/v3/endpoints-and-entities/entities/fixture#formation) [`ballCoordinates`](/v3/endpoints-and-entities/entities/fixture#ballcoordinate) [`scores`](/v3/endpoints-and-entities/entities/fixture#score) [`xGFixture`](/v3/endpoints-and-entities/entities/expected) [`pressure`](/v3/tutorials-and-guides/tutorials/includes/pressure-index) `expectedLineups` `predictedLineups` `matchfacts` `AIOverviews` ### **Related Entities:** Get an overview and explanation of all the fields returned in the API response. The related entities for the fixtures endpoints are: * [Fixture](/v3/endpoints-and-entities/entities/fixture#fixture) ### Postman We also offer detailed postman documentation with examples and a complete up-to-date version of all our endpoints. Below is a button that lets your fork the collection or import it. \ [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316?action=collection%2Ffork\&collection-url=entityId%3D11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316%26entityType%3Dcollection%26workspaceId%3D17c720d0-d97b-42a9-9ea7-23260ed53ddf) ### Code Example {% tabs %} {% tab title="Ruby" %} ```ruby require "uri" require "net/http" url = URI("https://api.sportmonks.com/v3/football/fixtures/head-to-head/{team_id_1}/{team_id2}?api_token=YOUR_TOKEN") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Get.new(url) response = https.request(request) puts response.read_body ``` {% endtab %} {% tab title="Python" %} ```python import http.client conn = http.client.HTTPSConnection("api.sportmonks.com") payload = '' headers = {} conn.request("GET", "/v3/football/fixtures/head-to-head/{team_id_1}/{team_id2}?api_token=YOUR_TOKEN", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) ``` {% endtab %} {% tab title="PHP" %} ```php 'https://api.sportmonks.com/v3/football/fixtures/head-to-head/{team_id_1}/{team_id2}?api_token=YOUR_TOKEN', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', )); $response = curl_exec($curl); curl_close($curl); echo $respons ``` {% endtab %} {% tab title="Java" %} ```java OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://api.sportmonks.com/v3/football/fixtures/head-to-head/{team_id_1}/{team_id2}?api_token=YOUR_TOKEN") .method("GET", null) .build(); Response response = client.newCall(request).execute(); ``` {% endtab %} {% tab title="Node.js" %} ``` var unirest = require('unirest'); var req = unirest('GET', 'https://api.sportmonks.com/v3/football/fixtures/head-to-head/{team_id_1}/{team_id2}?api_token=YOUR_TOKEN') .end(function (res) { if (res.error) throw new Error(res.error); console.log(res.raw_body); }); ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://api.sportmonks.com/v3/football/fixtures/head-to-head/{team_id_1}/{team_id2}?api_token=YOUR_TOKEN" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %} # GET Fixtures by Search by Name Returns all the fixtures that match your search query. {% tabs %} {% tab title="Base URL" %} ```javascript https://api.sportmonks.com/v3/football/fixtures/search/{searchQuery} ``` {% endtab %} {% tab title="Example Response" %} ```json { "id": 19146697, "sport_id": 1, "league_id": 501, "season_id": 23690, "stage_id": 77471570, "group_id": null, "aggregate_id": null, "round_id": 340573, "state_id": 5, "venue_id": 336296, "name": "Hearts vs Rangers", "starting_at": "2024-08-03 11:30:00", "result_info": "Game ended in draw.", "leg": "1/1", "details": null, "length": 90, "placeholder": false, "has_odds": true, "has_premium_odds": true, "starting_at_timestamp": 1722684600 } ``` {% endtab %} {% tab title="Field Description" %} | Field | Description | Type | | ------------- | ------------------------------------------------ | -------------- | | id | Refers the unique id of the fixture | integer | | sport\_id | Refers to the sport the fixture is played at | integer | | league\_id | Refers to the league the fixture is played in | integer | | season\_id | Refers to the seasons the fixture is played in | integer | | stage\_id | Refers to the stage the fixture is played in | integer | | group\_id | Refers to the group the fixture is played in | integer / null | | aggregate\_id | Refers to the aggregate the fixture is played at | integer / null | | state\_id | Refers to the state the fixture is played at | integer | | round\_id | Refers to the round the fixture is played at | integer / null | | state\_id | Refers to the state the fixture is played at | integer | | venue\_id | Refers to the venue the fixture is played at | integer / null | | name | Represents the name of the participants | string / null | | starting\_at | Datetime object representing the start time | date / null | | result\_info | Represents the final result info | string / null | | leg | Represents the leg of the fixture | string | | details | Represents details about the fixture | string / null | | length | Length of the fixture (minutes) | integer / null | | {% endtab %} | | | | {% endtabs %} | | | {% tabs %} {% tab title="Query Parameters" %}

Name	Required?	Description
`api_token`	YES Another option is to provide the API token in the header.	Your unique API token. Ex. ?api_token=YOUR_TOKEN
`include`	NO	Enrich the API response with more data by using includes. Ex. &include=participants;events
`select`	NO	Select specific fields on the base entity. Read how to select fields in our tutorial.
`sortBy`	NO	Order by specific fields on the base entity. For more information check out this page.
`filters`	NO	Filter the API response on multiple related entities. There are static filters and dynamic filters. Please find the possibilities in the Static and Dynamic Filter tab.
`locale`	NO	Translate name fields of the API Response in your selected language. Find more information and which languages are available on our translations page.

Static Filters	Available on Entity	Description	Example
`participantSearch`	Fixture	Filter on the matches of specific participants.	`&include=participants&filters=participantSearch:Celtic`
`todayDate`	Fixture	Filter all fixtures to find only the fixtures of today.	`&filters=todayDate`
`venues`	Fixture	Find all fixtures that are played in a specific venue.	`&include=venue&filters=venues:venueIDs` `&include=venue&filters=venues:10,12`
`Deleted`	Fixture	Filter on deleted fixtures only. This filter helps to keep your database in sync.	`&filters=Deleted`
`markets`	Odds	Filter the odds on a selection of markets separated by a comma.	`&include=odds&filters=markets:marketIDs` `&include=odds&filters=markets:12,14`
`bookmakers`	Odds	Filter the odds on a selection of bookmakers separated by a comma. (e.g: 2,14).	`&include=odds&filters=bookmakers:bookmakerIDs` `&include=odds&filters=bookmakers:2,14`
`WinningOdds`	Odds	Filter all winning odds.	`&include=odds&filters=WinningOdds`

{% endtab %} {% tab title="Dynamic Filters" %} The **dynamic filters** are based on entities and includes. Each dynamic filter uses an entity to filter on and one entity to apply the filter to. Below is an example with an explanation of how filters are set up. For more information, please look at our[ Filters page](/v3/api/request-options/filtering). {% hint style="info" %} Using an include? Check their respective filters on their entity page. For example if you use `&include=participants` you can apply [team-related filters](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#team). {% endhint %}

Dynamic Filters	Available on Entity	Description	Examples
`types`	Statistics, Events, Lineup, and way more. Check this endpoint for all possibilities.	Filter the statistics, events and more on a selection of type ids separated by a comma.	`&include=statistics.type&filters=fixturestatisticTypes:TypeIDs` `&include=statistics.type&filters=fixturestatisticTypes:42,49` `&include=events&filters=eventTypes:14` `&include=lineups.details.type&filters=lineupdetailTypes:118`
`states`	Fixtures Check this endpoint for all possibilities.	Filter the states of fixtures separated by a comma.	`&include=state&filters=fixtureStates:StateIDs` `&include=state&filters=fixtureStates:1`
`leagues`	Fixtures, Seasons, Standings, and way more. Check this endpoint for all possibilities.	Filter the fixtures based on leagues and their rounds.	`&filters=fixtureLeagues:leagueIDs` `&filters=fixtureLeagues:501,271`
`groups`	Fixtures, Standing, and more. Check this endpoint for all possibilities.	Filter the fixtures based on groups. Get their fixtures and standings.	`&include=group&filters=fixtureGroups:groupIDs` `&include=group&filters=fixtureGroups:246691`
`countries`	Coaches, Leagues, Players, Teams, and way more. Check this endpoint for all possibilities.	Filter the coaches, leagues, players and more based on countries.	`&include=coaches&filters=coachCountries:CountryIDs` `&include=coaches&filters=coachCountries:1161`
`seasons`	Statistics (players, team, coaches, referees), Standings, and way more. Check this endpoint for all possibilities.	Filter statistics, standings and topscorers based on seasons.	`&include=season.statistics&filters=seasonStatisticTypes:TypeIDs` `&include=season.statistics&filters=seasonStatisticTypes:52`

Parameter	Required	Description	Example
`order`	No	Returns fixtures ordered by starting_at (`asc` or `desc`). Defaults to asc	&order=desc
`per_page`	No	The amount of results to return per page (max 50.). Defaults to 25.	&per_page=30
`page`	No	You can paginate using the `has_more` parameter to determine if you can still propagate through the results.	&page=2

### Include depth You can use a total of `3` nested includes on this endpoint ### Include options [`sport`](https://docs.sportmonks.com/v3/core-api/) [`round`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#round) [`stage`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#stage) [`group`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#group) [`aggregate`](/v3/endpoints-and-entities/entities/fixture#aggregate) [`league`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#league) [`season`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season)[`coaches`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#coach) [`tvStations`](/v3/endpoints-and-entities/entities/other#tvstation) [`venue`](/v3/endpoints-and-entities/entities/other#venue) [`state`](/v3/endpoints-and-entities/entities/other#state) [`weatherReport`](/v3/endpoints-and-entities/entities/other#weatherreport) [`lineups`](/v3/endpoints-and-entities/entities/fixture#lineup) [`events`](/v3/endpoints-and-entities/entities/fixture#event) [`timeline`](/v3/endpoints-and-entities/entities/fixture#event) [`comments`](/v3/endpoints-and-entities/entities/other#commentary) [`trends`](/v3/endpoints-and-entities/entities/statistic#trend) [`statistics`](/v3/endpoints-and-entities/entities/statistic#fixturestatistic) [`periods`](/v3/endpoints-and-entities/entities/fixture#period) [`participants` ](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#team)[`odds`](/v3/endpoints-and-entities/entities/odd-and-prediction#odd)[`premiumOdds`](https://docs.sportmonks.com/football/endpoints-and-entities/entities/odd-and-prediction#premium-odd) [`inplayOdds`](/v3/endpoints-and-entities/entities/odd-and-prediction#inplayodd) [`prematchNews`](/v3/endpoints-and-entities/entities/other#news) [`postmatchNews`](/v3/endpoints-and-entities/entities/other#news) [`metadata`](/v3/endpoints-and-entities/entities/other#metadata) [`sidelined`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#sidelined)[`predictions`](/v3/endpoints-and-entities/entities/odd-and-prediction#prediction-valuebet) [`referees`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#referees) [`formations`](/v3/endpoints-and-entities/entities/fixture#formation) [`ballCoordinates`](/v3/endpoints-and-entities/entities/fixture#ballcoordinate) [`scores`](/v3/endpoints-and-entities/entities/fixture#score) [`xGFixture`](/v3/endpoints-and-entities/entities/expected) [`pressure`](/v3/tutorials-and-guides/tutorials/includes/pressure-index) `expectedLineups` `predictedLineups` `matchfacts` `AIOverviews` ### **Related Entities:** Get an overview and explanation of all the fields returned in the API response. The related entities for the fixtures endpoints are: * [Fixture](/v3/endpoints-and-entities/entities/fixture#fixture) ### Postman We also offer detailed postman documentation with examples and a complete up-to-date version of all our endpoints. Below is a button that lets your fork the collection or import it. \ [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316?action=collection%2Ffork\&collection-url=entityId%3D11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316%26entityType%3Dcollection%26workspaceId%3D17c720d0-d97b-42a9-9ea7-23260ed53ddf) ### Code Example {% tabs %} {% tab title="Ruby" %} ```ruby require "uri" require "net/http" url = URI("https://api.sportmonks.com/v3/football/fixtures/search/{searchQuery}?api_token=YOUR_TOKEN") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Get.new(url) response = https.request(request) puts response.read_body ``` {% endtab %} {% tab title="Python" %} ```python import http.client conn = http.client.HTTPSConnection("api.sportmonks.com") payload = '' headers = {} conn.request("GET", "/v3/football/fixtures/search/{searchQuery}?api_token=YOUR_TOKEN", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) ``` {% endtab %} {% tab title="PHP" %} ```php 'https://api.sportmonks.com/v3/football/fixtures/search/{searchQuery}?api_token=YOUR_TOKEN', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', )); $response = curl_exec($curl); curl_close($curl); echo $respons ``` {% endtab %} {% tab title="Java" %} ```java OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://api.sportmonks.com/v3/football/fixtures/search/{searchQuery}?api_token=YOUR_TOKEN") .method("GET", null) .build(); Response response = client.newCall(request).execute(); ``` {% endtab %} {% tab title="Node.js" %} ``` var unirest = require('unirest'); var req = unirest('GET', 'https://api.sportmonks.com/v3/football/fixtures/search/{searchQuery}?api_token=YOUR_TOKEN') .end(function (res) { if (res.error) throw new Error(res.error); console.log(res.raw_body); }); ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://api.sportmonks.com/v3/football/fixtures/search/{searchQuery}?api_token=YOUR_TOKEN" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %} # GET Upcoming Fixtures by Market ID Returns all the fixtures from your requested market ID. {% tabs %} {% tab title="Base URL" %} ```javascript https://api.sportmonks.com/v3/football/fixtures/upcoming/markets/{marketID} ``` {% endtab %} {% tab title="Example Response" %} ```json { "data": [ { "id": 19230783, "sport_id": 1, "league_id": 612, "season_id": 24157, "stage_id": 77472830, "group_id": 251075, "aggregate_id": null, "round_id": 350222, "state_id": 1, "venue_id": 4241, "name": "Nyva Ternopil' vs Epitsentr Dunayivtsi", "starting_at": "2024-08-08 14:00:00", "result_info": null, "leg": "1/1", "details": null, "length": 90, "placeholder": false, "has_odds": true, "has_premium_odds": true, "starting_at_timestamp": 1723125600 }, { "id": 19110346, "sport_id": 1, "league_id": 396, "season_id": 23369, "stage_id": 77470477, "group_id": null, "aggregate_id": null, "round_id": 336772, "state_id": 1, "venue_id": 4149, "name": "Taraz vs Arys", "starting_at": "2024-08-08 14:00:00", "result_info": null, "leg": "1/1", "details": null, "length": 90, "placeholder": false, "has_odds": true, "has_premium_odds": true, "starting_at_timestamp": 1723125600 ``` {% endtab %} {% tab title="Field Description" %} | Field | Description | Type | | ------------- | ------------------------------------------------ | -------------- | | id | Refers the unique id of the fixture | integer | | sport\_id | Refers to the sport the fixture is played at | integer | | league\_id | Refers to the league the fixture is played in | integer | | season\_id | Refers to the seasons the fixture is played in | integer | | stage\_id | Refers to the stage the fixture is played in | integer | | group\_id | Refers to the group the fixture is played in | integer / null | | aggregate\_id | Refers to the aggregate the fixture is played at | integer / null | | state\_id | Refers to the state the fixture is played at | integer | | round\_id | Refers to the round the fixture is played at | integer / null | | state\_id | Refers to the state the fixture is played at | integer | | venue\_id | Refers to the venue the fixture is played at | integer / null | | name | Represents the name of the participants | string / null | | starting\_at | Datetime object representing the start time | date / null | | result\_info | Represents the final result info | string / null | | leg | Represents the leg of the fixture | string | | details | Represents details about the fixture | string / null | | length | Length of the fixture (minutes) | integer / null | | {% endtab %} | | | | {% endtabs %} | | | {% tabs %} {% tab title="Query Parameters" %}

Name	Required?	Description
`api_token`	YES Another option is to provide the API token in the header.	Your unique API token. Ex. ?api_token=YOUR_TOKEN
`include`	NO	Enrich the API response with more data by using includes. Ex. &include=participants;events
`select`	NO	Select specific fields on the base entity. Read how to select fields in our tutorial.
`sortBy`	NO	Order by specific fields on the base entity. For more information check out this page.
`filters`	NO	Filter the API response on multiple related entities. There are static filters and dynamic filters. Please find the possibilities in the Static and Dynamic Filter tab.
`locale`	NO	Translate name fields of the API Response in your selected language. Find more information and which languages are available on our translations page.

Static Filters	Available on Entity	Description	Example
`participantSearch`	Fixture	Filter on the matches of specific participants.	`&include=participants&filters=participantSearch:Celtic`
`todayDate`	Fixture	Filter all fixtures to find only the fixtures of today.	`&filters=todayDate`
`venues`	Fixture	Find all fixtures that are played in a specific venue.	`&include=venue&filters=venues:venueIDs` `&include=venue&filters=venues:10,12`
`Deleted`	Fixture	Filter on deleted fixtures only. This filter helps to keep your database in sync.	`&filters=Deleted`
`markets`	Odds	Filter the odds on a selection of markets separated by a comma.	`&include=odds&filters=markets:marketIDs` `&include=odds&filters=markets:12,14`
`bookmakers`	Odds	Filter the odds on a selection of bookmakers separated by a comma. (e.g: 2,14).	`&include=odds&filters=bookmakers:bookmakerIDs` `&include=odds&filters=bookmakers:2,14`
`WinningOdds`	Odds	Filter all winning odds.	`&include=odds&filters=WinningOdds`

{% endtab %} {% tab title="Dynamic Filters" %} The **dynamic filters** are based on entities and includes. Each dynamic filter uses an entity to filter on and one entity to apply the filter to. Below is an example with an explanation of how filters are set up. For more information, please look at our[ Filters page](/v3/api/request-options/filtering). {% hint style="info" %} Using an include? Check their respective filters on their entity page. For example if you use `&include=participants` you can apply [team-related filters](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#team). {% endhint %}

Dynamic Filters	Available on Entity	Description	Examples
`types`	Statistics, Events, Lineup, and way more. Check this endpoint for all possibilities.	Filter the statistics, events and more on a selection of type ids separated by a comma.	`&include=statistics.type&filters=fixturestatisticTypes:TypeIDs` `&include=statistics.type&filters=fixturestatisticTypes:42,49` `&include=events&filters=eventTypes:14` `&include=lineups.details.type&filters=lineupdetailTypes:118`
`states`	Fixtures Check this endpoint for all possibilities.	Filter the states of fixtures separated by a comma.	`&include=state&filters=fixtureStates:StateIDs` `&include=state&filters=fixtureStates:1`
`leagues`	Fixtures, Seasons, Standings, and way more. Check this endpoint for all possibilities.	Filter the fixtures based on leagues and their rounds.	`&filters=fixtureLeagues:leagueIDs` `&filters=fixtureLeagues:501,271`
`groups`	Fixtures, Standing, and more. Check this endpoint for all possibilities.	Filter the fixtures based on groups. Get their fixtures and standings.	`&include=group&filters=fixtureGroups:groupIDs` `&include=group&filters=fixtureGroups:246691`
`countries`	Coaches, Leagues, Players, Teams, and way more. Check this endpoint for all possibilities.	Filter the coaches, leagues, players and more based on countries.	`&include=coaches&filters=coachCountries:CountryIDs` `&include=coaches&filters=coachCountries:1161`
`seasons`	Statistics (players, team, coaches, referees), Standings, and way more. Check this endpoint for all possibilities.	Filter statistics, standings and topscorers based on seasons.	`&include=season.statistics&filters=seasonStatisticTypes:TypeIDs` `&include=season.statistics&filters=seasonStatisticTypes:52`

Parameter	Required	Description	Example
`order`	No	Returns fixtures ordered by starting_at (`asc` or `desc`). Defaults to asc	&order=desc
`per_page`	No	The amount of results to return per page (max 50.). Defaults to 25.	&per_page=30
`page`	No	You can paginate using the `has_more` parameter to determine if you can still propagate through the results.	&page=2

### Include depth You can use a total of `3` nested includes on this endpoint ### Include options [`sport`](https://docs.sportmonks.com/v3/core-api/) [`round`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#round) [`stage`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#stage) [`group`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#group) [`aggregate`](/v3/endpoints-and-entities/entities/fixture#aggregate) [`league`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#league) [`season`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season)[`coaches`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#coach) [`tvStations`](/v3/endpoints-and-entities/entities/other#tvstation) [`venue`](/v3/endpoints-and-entities/entities/other#venue) [`state`](/v3/endpoints-and-entities/entities/other#state) [`weatherReport`](/v3/endpoints-and-entities/entities/other#weatherreport) [`lineups`](/v3/endpoints-and-entities/entities/fixture#lineup) [`events`](/v3/endpoints-and-entities/entities/fixture#event) [`timeline`](/v3/endpoints-and-entities/entities/fixture#event) [`comments`](/v3/endpoints-and-entities/entities/other#commentary) [`trends`](/v3/endpoints-and-entities/entities/statistic#trend) [`statistics`](/v3/endpoints-and-entities/entities/statistic#fixturestatistic) [`periods`](/v3/endpoints-and-entities/entities/fixture#period) [`participants` ](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#team)[`odds`](/v3/endpoints-and-entities/entities/odd-and-prediction#odd)[`premiumOdds`](https://docs.sportmonks.com/football/endpoints-and-entities/entities/odd-and-prediction#premium-odd) [`inplayOdds`](/v3/endpoints-and-entities/entities/odd-and-prediction#inplayodd) [`prematchNews`](/v3/endpoints-and-entities/entities/other#news) [`postmatchNews`](/v3/endpoints-and-entities/entities/other#news) [`metadata`](/v3/endpoints-and-entities/entities/other#metadata) [`sidelined`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#sidelined)[`predictions`](/v3/endpoints-and-entities/entities/odd-and-prediction#prediction-valuebet) [`referees`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#referees) [`formations`](/v3/endpoints-and-entities/entities/fixture#formation) [`ballCoordinates`](/v3/endpoints-and-entities/entities/fixture#ballcoordinate) [`scores`](/v3/endpoints-and-entities/entities/fixture#score) [`xGFixture`](/v3/endpoints-and-entities/entities/expected) [`pressure`](/v3/tutorials-and-guides/tutorials/includes/pressure-index) `expectedLineups` `predictedLineups` `matchfacts` `AIOverviews` ### **Related Entities:** Get an overview and explanation of all the fields returned in the API response. The related entities for the fixtures endpoints are: * [Fixture](/v3/endpoints-and-entities/entities/fixture#fixture) ### Postman We also offer detailed postman documentation with examples and a complete up-to-date version of all our endpoints. Below is a button that lets your fork the collection or import it. \ [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316?action=collection%2Ffork\&collection-url=entityId%3D11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316%26entityType%3Dcollection%26workspaceId%3D17c720d0-d97b-42a9-9ea7-23260ed53ddf) ### Code Example {% tabs %} {% tab title="Ruby" %} ```ruby require "uri" require "net/http" url = URI("https://api.sportmonks.com/v3/football/fixtures/upcoming/markets/{marketID}?api_token=YOUR_TOKEN") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Get.new(url) response = https.request(request) puts response.read_body ``` {% endtab %} {% tab title="Python" %} ```python import http.client conn = http.client.HTTPSConnection("api.sportmonks.com") payload = '' headers = {} conn.request("GET", "/v3/football/fixtures/upcoming/markets/{marketID}?api_token=YOUR_TOKEN", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) ``` {% endtab %} {% tab title="PHP" %} ```php 'https://api.sportmonks.com/v3/football/fixtures/upcoming/markets/{marketID}?api_token=YOUR_TOKEN', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', )); $response = curl_exec($curl); curl_close($curl); echo $respons ``` {% endtab %} {% tab title="Java" %} ```java OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://api.sportmonks.com/v3/football/fixtures/upcoming/markets/{marketID}?api_token=YOUR_TOKEN") .method("GET", null) .build(); Response response = client.newCall(request).execute(); ``` {% endtab %} {% tab title="Node.js" %} ``` var unirest = require('unirest'); var req = unirest('GET', 'https://api.sportmonks.com/v3/football/fixtures/upcoming/markets/{marketID}?api_token=YOUR_TOKEN') .end(function (res) { if (res.error) throw new Error(res.error); console.log(res.raw_body); }); ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://api.sportmonks.com/v3/football/fixtures/upcoming/markets/{marketID}?api_token=YOUR_TOKEN" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %} # GET Upcoming Fixtures by TV Station ID Returns all the upcoming fixtures available in one or more countries from your requested Tv-station ID. {% tabs %} {% tab title="Base URL" %} ```javascript https://api.sportmonks.com/v3/football/fixtures/upcoming/tv-stations/{tvStationId} ``` {% endtab %} {% tab title="Example Response" %} ```json { "data": [ { "id": 19215284, "sport_id": 1, "league_id": 920, "season_id": 24083, "stage_id": 77472639, "group_id": null, "aggregate_id": null, "round_id": 348691, "state_id": 1, "venue_id": 10828, "name": "Al Ahli vs Moghayer Al Sarhan", "starting_at": "2024-08-08 15:00:00", "result_info": null, "leg": "1/1", "details": null, "length": 90, "placeholder": false, "has_odds": true, "has_premium_odds": true, "starting_at_timestamp": 1723129200 }, { "id": 19194503, "sport_id": 1, "league_id": 5, "season_id": 23620, "stage_id": 77471329, "group_id": null, "aggregate_id": 55025, "round_id": null, "state_id": 1, "venue_id": 8098, "name": "Molde vs Cercle Brugge", "starting_at": "2024-08-08 17:00:00", "result_info": null, "leg": "1/2", "details": null, "length": 90, "placeholder": false, "has_odds": true, "has_premium_odds": true, "starting_at_timestamp": 1723136400 }, ``` {% endtab %} {% tab title="Field Description" %} | Field | Description | Type | | ------------- | ------------------------------------------------ | -------------- | | id | Refers the unique id of the fixture | integer | | sport\_id | Refers to the sport the fixture is played at | integer | | league\_id | Refers to the league the fixture is played in | integer | | season\_id | Refers to the seasons the fixture is played in | integer | | stage\_id | Refers to the stage the fixture is played in | integer | | group\_id | Refers to the group the fixture is played in | integer / null | | aggregate\_id | Refers to the aggregate the fixture is played at | integer / null | | state\_id | Refers to the state the fixture is played at | integer | | round\_id | Refers to the round the fixture is played at | integer / null | | state\_id | Refers to the state the fixture is played at | integer | | venue\_id | Refers to the venue the fixture is played at | integer / null | | name | Represents the name of the participants | string / null | | starting\_at | Datetime object representing the start time | date / null | | result\_info | Represents the final result info | string / null | | leg | Represents the leg of the fixture | string | | details | Represents details about the fixture | string / null | | length | Length of the fixture (minutes) | integer / null | | {% endtab %} | | | | {% endtabs %} | | | {% tabs %} {% tab title="Query Parameters" %}

Name	Required?	Description
`api_token`	YES Another option is to provide the API token in the header.	Your unique API token. Ex. ?api_token=YOUR_TOKEN
`include`	NO	Enrich the API response with more data by using includes. Ex. &include=participants;events
`select`	NO	Select specific fields on the base entity. Read how to select fields in our tutorial.
`sortBy`	NO	Order by specific fields on the base entity. For more information check out this page.
`filters`	NO	Filter the API response on multiple related entities. There are static filters and dynamic filters. Please find the possibilities in the Static and Dynamic Filter tab.
`locale`	NO	Translate name fields of the API Response in your selected language. Find more information and which languages are available on our translations page.

Static Filters	Available on Entity	Description	Example
`participantSearch`	Fixture	Filter on the matches of specific participants.	`&include=participants&filters=participantSearch:Celtic`
`todayDate`	Fixture	Filter all fixtures to find only the fixtures of today.	`&filters=todayDate`
`venues`	Fixture	Find all fixtures that are played in a specific venue.	`&include=venue&filters=venues:venueIDs` `&include=venue&filters=venues:10,12`
`Deleted`	Fixture	Filter on deleted fixtures only. This filter helps to keep your database in sync.	`&filters=Deleted`
`markets`	Odds	Filter the odds on a selection of markets separated by a comma.	`&include=odds&filters=markets:marketIDs` `&include=odds&filters=markets:12,14`
`bookmakers`	Odds	Filter the odds on a selection of bookmakers separated by a comma. (e.g: 2,14).	`&include=odds&filters=bookmakers:bookmakerIDs` `&include=odds&filters=bookmakers:2,14`
`WinningOdds`	Odds	Filter all winning odds.	`&include=odds&filters=WinningOdds`

{% endtab %} {% tab title="Dynamic Filters" %} The **dynamic filters** are based on entities and includes. Each dynamic filter uses an entity to filter on and one entity to apply the filter to. Below is an example with an explanation of how filters are set up. For more information, please look at our[ Filters page](/v3/api/request-options/filtering). {% hint style="info" %} Using an include? Check their respective filters on their entity page. For example if you use `&include=participants` you can apply [team-related filters](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#team). {% endhint %}

Dynamic Filters	Available on Entity	Description	Examples
`types`	Statistics, Events, Lineup, and way more. Check this endpoint for all possibilities.	Filter the statistics, events and more on a selection of type ids separated by a comma.	`&include=statistics.type&filters=fixturestatisticTypes:TypeIDs` `&include=statistics.type&filters=fixturestatisticTypes:42,49` `&include=events&filters=eventTypes:14` `&include=lineups.details.type&filters=lineupdetailTypes:118`
`states`	Fixtures Check this endpoint for all possibilities.	Filter the states of fixtures separated by a comma.	`&include=state&filters=fixtureStates:StateIDs` `&include=state&filters=fixtureStates:1`
`leagues`	Fixtures, Seasons, Standings, and way more. Check this endpoint for all possibilities.	Filter the fixtures based on leagues and their rounds.	`&filters=fixtureLeagues:leagueIDs` `&filters=fixtureLeagues:501,271`
`groups`	Fixtures, Standing, and more. Check this endpoint for all possibilities.	Filter the fixtures based on groups. Get their fixtures and standings.	`&include=group&filters=fixtureGroups:groupIDs` `&include=group&filters=fixtureGroups:246691`
`countries`	Coaches, Leagues, Players, Teams, and way more. Check this endpoint for all possibilities.	Filter the coaches, leagues, players and more based on countries.	`&include=coaches&filters=coachCountries:CountryIDs` `&include=coaches&filters=coachCountries:1161`
`seasons`	Statistics (players, team, coaches, referees), Standings, and way more. Check this endpoint for all possibilities.	Filter statistics, standings and topscorers based on seasons.	`&include=season.statistics&filters=seasonStatisticTypes:TypeIDs` `&include=season.statistics&filters=seasonStatisticTypes:52`

Parameter	Required	Description	Example
`order`	No	Returns fixtures ordered by starting_at (`asc` or `desc`). Defaults to asc	&order=desc
`per_page`	No	The amount of results to return per page (max 50.). Defaults to 25.	&per_page=30
`page`	No	You can paginate using the `has_more` parameter to determine if you can still propagate through the results.	&page=2

### Include depth You can use a total of `3` nested includes on this endpoint ### Include options [`sport`](https://docs.sportmonks.com/v3/core-api/) [`round`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#round) [`stage`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#stage) [`group`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#group) [`aggregate`](/v3/endpoints-and-entities/entities/fixture#aggregate) [`league`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#league) [`season`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season)[`coaches`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#coach) [`tvStations`](/v3/endpoints-and-entities/entities/other#tvstation) [`venue`](/v3/endpoints-and-entities/entities/other#venue) [`state`](/v3/endpoints-and-entities/entities/other#state) [`weatherReport`](/v3/endpoints-and-entities/entities/other#weatherreport) [`lineups`](/v3/endpoints-and-entities/entities/fixture#lineup) [`events`](/v3/endpoints-and-entities/entities/fixture#event) [`timeline`](/v3/endpoints-and-entities/entities/fixture#event) [`comments`](/v3/endpoints-and-entities/entities/other#commentary) [`trends`](/v3/endpoints-and-entities/entities/statistic#trend) [`statistics`](/v3/endpoints-and-entities/entities/statistic#fixturestatistic) [`periods`](/v3/endpoints-and-entities/entities/fixture#period) [`participants` ](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#team)[`odds`](/v3/endpoints-and-entities/entities/odd-and-prediction#odd)[`premiumOdds`](https://docs.sportmonks.com/football/endpoints-and-entities/entities/odd-and-prediction#premium-odd) [`inplayOdds`](/v3/endpoints-and-entities/entities/odd-and-prediction#inplayodd) [`prematchNews`](/v3/endpoints-and-entities/entities/other#news) [`postmatchNews`](/v3/endpoints-and-entities/entities/other#news) [`metadata`](/v3/endpoints-and-entities/entities/other#metadata) [`sidelined`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#sidelined)[`predictions`](/v3/endpoints-and-entities/entities/odd-and-prediction#prediction-valuebet) [`referees`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#referees) [`formations`](/v3/endpoints-and-entities/entities/fixture#formation) [`ballCoordinates`](/v3/endpoints-and-entities/entities/fixture#ballcoordinate) [`scores`](/v3/endpoints-and-entities/entities/fixture#score) [`xGFixture`](/v3/endpoints-and-entities/entities/expected) [`pressure`](/v3/tutorials-and-guides/tutorials/includes/pressure-index) `expectedLineups` `predictedLineups` `matchfacts` `AIOverviews` ### **Related Entities:** Get an overview and explanation of all the fields returned in the API response. The related entities for the fixtures endpoints are: * [Fixture](/v3/endpoints-and-entities/entities/fixture#fixture) ### Postman We also offer detailed postman documentation with examples and a complete up-to-date version of all our endpoints. Below is a button that lets your fork the collection or import it. \ [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316?action=collection%2Ffork\&collection-url=entityId%3D11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316%26entityType%3Dcollection%26workspaceId%3D17c720d0-d97b-42a9-9ea7-23260ed53ddf) ### Code Example {% tabs %} {% tab title="Ruby" %} ```ruby require "uri" require "net/http" url = URI("https://api.sportmonks.com/v3/football/fixtures/upcoming/tv-stations/{TVstationID}?api_token=YOUR_TOKEN") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Get.new(url) response = https.request(request) puts response.read_body ``` {% endtab %} {% tab title="Python" %} ```python import http.client conn = http.client.HTTPSConnection("api.sportmonks.com") payload = '' headers = {} conn.request("GET", "/v3/football/fixtures/upcoming/tv-stations/{TVstationsID}?api_token=YOUR_TOKEN", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) ``` {% endtab %} {% tab title="PHP" %} ```php 'https://api.sportmonks.com/v3/football/fixtures/upcoming/tv-stations/{TVstationsID}?api_token=YOUR_TOKEN', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', )); $response = curl_exec($curl); curl_close($curl); echo $respons ``` {% endtab %} {% tab title="Java" %} ```java OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://api.sportmonks.com/v3/football/fixtures/upcoming/tv-stations/{TVstationsID}?api_token=YOUR_TOKEN") .method("GET", null) .build(); Response response = client.newCall(request).execute(); ``` {% endtab %} {% tab title="Node.js" %} ``` var unirest = require('unirest'); var req = unirest('GET', 'https://api.sportmonks.com/v3/football/fixtures/upcoming/tv-stations/{TVstationsID}?api_token=YOUR_TOKEN') .end(function (res) { if (res.error) throw new Error(res.error); console.log(res.raw_body); }); ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://api.sportmonks.com/v3/football/fixtures/upcoming/tv-stations/{TVstationsID}?api_token=YOUR_TOKEN" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %} # GET Past Fixtures by TV Station ID Returns all the past fixtures that were available in one or more countries from your requested Tv-station ID. {% tabs %} {% tab title="Base URL" %} ```javascript https://api.sportmonks.com/v3/football/fixtures/past/tv-stations/{tvStationId} ``` {% endtab %} {% tab title="Example Response" %} ```json { "data": [ { "id": 19190779, "sport_id": 1, "league_id": 654, "season_id": 23161, "stage_id": 77469785, "group_id": null, "aggregate_id": 54864, "round_id": null, "state_id": 8, "venue_id": 1718, "name": "Grêmio vs Corinthians", "starting_at": "2024-08-08 00:30:00", "result_info": "Grêmio won after penalties.", "leg": "2/2", "details": null, "length": 90, "placeholder": false, "has_odds": true, "has_premium_odds": true, "starting_at_timestamp": 1723077000 }, { "id": 19190781, "sport_id": 1, "league_id": 654, "season_id": 23161, "stage_id": 77469785, "group_id": null, "aggregate_id": 54865, "round_id": null, "state_id": 5, "venue_id": 392, "name": "Fluminense vs Juventude", "starting_at": "2024-08-08 00:30:00", "result_info": "Game ended in draw.", "leg": "2/2", "details": null, "length": 90, "placeholder": false, "has_odds": true, "has_premium_odds": true, "starting_at_timestamp": 1723077000 ``` {% endtab %} {% tab title="Field Description" %} | Field | Description | Type | | ------------- | ------------------------------------------------ | -------------- | | id | Refers the unique id of the fixture | integer | | sport\_id | Refers to the sport the fixture is played at | integer | | league\_id | Refers to the league the fixture is played in | integer | | season\_id | Refers to the seasons the fixture is played in | integer | | stage\_id | Refers to the stage the fixture is played in | integer | | group\_id | Refers to the group the fixture is played in | integer / null | | aggregate\_id | Refers to the aggregate the fixture is played at | integer / null | | state\_id | Refers to the state the fixture is played at | integer | | round\_id | Refers to the round the fixture is played at | integer / null | | state\_id | Refers to the state the fixture is played at | integer | | venue\_id | Refers to the venue the fixture is played at | integer / null | | name | Represents the name of the participants | string / null | | starting\_at | Datetime object representing the start time | date / null | | result\_info | Represents the final result info | string / null | | leg | Represents the leg of the fixture | string | | details | Represents details about the fixture | string / null | | length | Length of the fixture (minutes) | integer / null | | {% endtab %} | | | | {% endtabs %} | | | {% tabs %} {% tab title="Query Parameters" %}

Name	Required?	Description
`api_token`	YES Another option is to provide the API token in the header.	Your unique API token. Ex. ?api_token=YOUR_TOKEN
`include`	NO	Enrich the API response with more data by using includes. Ex. &include=participants;events
`select`	NO	Select specific fields on the base entity. Read how to select fields in our tutorial.
`sortBy`	NO	Order by specific fields on the base entity. For more information check out this page.
`filters`	NO	Filter the API response on multiple related entities. There are static filters and dynamic filters. Please find the possibilities in the Static and Dynamic Filter tab.
`locale`	NO	Translate name fields of the API Response in your selected language. Find more information and which languages are available on our translations page.

Static Filters	Available on Entity	Description	Example
`participantSearch`	Fixture	Filter on the matches of specific participants.	`&include=participants&filters=participantSearch:Celtic`
`todayDate`	Fixture	Filter all fixtures to find only the fixtures of today.	`&filters=todayDate`
`venues`	Fixture	Find all fixtures that are played in a specific venue.	`&include=venue&filters=venues:venueIDs` `&include=venue&filters=venues:10,12`
`Deleted`	Fixture	Filter on deleted fixtures only. This filter helps to keep your database in sync.	`&filters=Deleted`
`markets`	Odds	Filter the odds on a selection of markets separated by a comma.	`&include=odds&filters=markets:marketIDs` `&include=odds&filters=markets:12,14`
`bookmakers`	Odds	Filter the odds on a selection of bookmakers separated by a comma. (e.g: 2,14).	`&include=odds&filters=bookmakers:bookmakerIDs` `&include=odds&filters=bookmakers:2,14`
`WinningOdds`	Odds	Filter all winning odds.	`&include=odds&filters=WinningOdds`

{% endtab %} {% tab title="Dynamic Filters" %} The **dynamic filters** are based on entities and includes. Each dynamic filter uses an entity to filter on and one entity to apply the filter to. Below is an example with an explanation of how filters are set up. For more information, please look at our[ Filters page](/v3/api/request-options/filtering). {% hint style="info" %} Using an include? Check their respective filters on their entity page. For example if you use `&include=participants` you can apply [team-related filters](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#team). {% endhint %}

Dynamic Filters	Available on Entity	Description	Examples
`types`	Statistics, Events, Lineup, and way more. Check this endpoint for all possibilities.	Filter the statistics, events and more on a selection of type ids separated by a comma.	`&include=statistics.type&filters=fixturestatisticTypes:TypeIDs` `&include=statistics.type&filters=fixturestatisticTypes:42,49` `&include=events&filters=eventTypes:14` `&include=lineups.details.type&filters=lineupdetailTypes:118`
`states`	Fixtures Check this endpoint for all possibilities.	Filter the states of fixtures separated by a comma.	`&include=state&filters=fixtureStates:StateIDs` `&include=state&filters=fixtureStates:1`
`leagues`	Fixtures, Seasons, Standings, and way more. Check this endpoint for all possibilities.	Filter the fixtures based on leagues and their rounds.	`&filters=fixtureLeagues:leagueIDs` `&filters=fixtureLeagues:501,271`
`groups`	Fixtures, Standing, and more. Check this endpoint for all possibilities.	Filter the fixtures based on groups. Get their fixtures and standings.	`&include=group&filters=fixtureGroups:groupIDs` `&include=group&filters=fixtureGroups:246691`
`countries`	Coaches, Leagues, Players, Teams, and way more. Check this endpoint for all possibilities.	Filter the coaches, leagues, players and more based on countries.	`&include=coaches&filters=coachCountries:CountryIDs` `&include=coaches&filters=coachCountries:1161`
`seasons`	Statistics (players, team, coaches, referees), Standings, and way more. Check this endpoint for all possibilities.	Filter statistics, standings and topscorers based on seasons.	`&include=season.statistics&filters=seasonStatisticTypes:TypeIDs` `&include=season.statistics&filters=seasonStatisticTypes:52`

Parameter	Required	Description	Example
`order`	No	Returns fixtures ordered by starting_at (`asc` or `desc`). Defaults to asc	&order=desc
`per_page`	No	The amount of results to return per page (max 50.). Defaults to 25.	&per_page=30
`page`	No	You can paginate using the `has_more` parameter to determine if you can still propagate through the results.	&page=2

### Include depth You can use a total of `3` nested includes on this endpoint ### Include options [`sport`](https://docs.sportmonks.com/v3/core-api/) [`round`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#round) [`stage`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#stage) [`group`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#group) [`aggregate`](/v3/endpoints-and-entities/entities/fixture#aggregate) [`league`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#league) [`season`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season)[`coaches`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#coach) [`tvStations`](/v3/endpoints-and-entities/entities/other#tvstation) [`venue`](/v3/endpoints-and-entities/entities/other#venue) [`state`](/v3/endpoints-and-entities/entities/other#state) [`weatherReport`](/v3/endpoints-and-entities/entities/other#weatherreport) [`lineups`](/v3/endpoints-and-entities/entities/fixture#lineup) [`events`](/v3/endpoints-and-entities/entities/fixture#event) [`timeline`](/v3/endpoints-and-entities/entities/fixture#event) [`comments`](/v3/endpoints-and-entities/entities/other#commentary) [`trends`](/v3/endpoints-and-entities/entities/statistic#trend) [`statistics`](/v3/endpoints-and-entities/entities/statistic#fixturestatistic) [`periods`](/v3/endpoints-and-entities/entities/fixture#period) [`participants` ](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#team)[`odds`](/v3/endpoints-and-entities/entities/odd-and-prediction#odd) [`premiumOdds`](https://docs.sportmonks.com/football/endpoints-and-entities/entities/odd-and-prediction#premium-odd)[`inplayOdds`](/v3/endpoints-and-entities/entities/odd-and-prediction#inplayodd) [`prematchNews`](/v3/endpoints-and-entities/entities/other#news) [`postmatchNews`](/v3/endpoints-and-entities/entities/other#news) [`metadata`](/v3/endpoints-and-entities/entities/other#metadata) [`sidelined`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#sidelined)[`predictions`](/v3/endpoints-and-entities/entities/odd-and-prediction#prediction-valuebet) [`referees`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#referees) [`formations`](/v3/endpoints-and-entities/entities/fixture#formation) [`ballCoordinates`](/v3/endpoints-and-entities/entities/fixture#ballcoordinate) [`scores`](/v3/endpoints-and-entities/entities/fixture#score) [`xGFixture`](/v3/endpoints-and-entities/entities/expected) [`pressure`](/v3/tutorials-and-guides/tutorials/includes/pressure-index) `expectedLineups` `predictedLineups` `matchfacts` `AIOverviews` ### **Related Entities:** Get an overview and explanation of all the fields returned in the API response. The related entities for the fixtures endpoints are: * [Fixture](/v3/endpoints-and-entities/entities/fixture#fixture) ### Postman We also offer detailed postman documentation with examples and a complete up-to-date version of all our endpoints. Below is a button that lets your fork the collection or import it. \ [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316?action=collection%2Ffork\&collection-url=entityId%3D11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316%26entityType%3Dcollection%26workspaceId%3D17c720d0-d97b-42a9-9ea7-23260ed53ddf) ### Code Example {% tabs %} {% tab title="Ruby" %} ```ruby require "uri" require "net/http" url = URI("https://api.sportmonks.com/v3/football/fixtures/upcoming/tv-stations/{TVstationID}?api_token=YOUR_TOKEN") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Get.new(url) response = https.request(request) puts response.read_body ``` {% endtab %} {% tab title="Python" %} ```python import http.client conn = http.client.HTTPSConnection("api.sportmonks.com") payload = '' headers = {} conn.request("GET", "/v3/football/fixtures/upcoming/tv-stations/{TVstationID}?api_token=YOUR_TOKEN", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) ``` {% endtab %} {% tab title="PHP" %} ```php 'https://api.sportmonks.com/v3/football/fixtures/upcoming/tv-stations/{TVstationID}?api_token=YOUR_TOKEN', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', )); $response = curl_exec($curl); curl_close($curl); echo $respons ``` {% endtab %} {% tab title="Java" %} ```java OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://api.sportmonks.com/v3/football/fixtures/upcoming/tv-stations/{TVstationID}?api_token=YOUR_TOKEN") .method("GET", null) .build(); Response response = client.newCall(request).execute(); ``` {% endtab %} {% tab title="Node.js" %} ``` var unirest = require('unirest'); var req = unirest('GET', 'https://api.sportmonks.com/v3/football/fixtures/upcoming/tv-stations/{TVstationID}?api_token=YOUR_TOKEN') .end(function (res) { if (res.error) throw new Error(res.error); console.log(res.raw_body); }); ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://api.sportmonks.com/v3/football/fixtures/upcoming/tv-stations/{TVstationID}?api_token=YOUR_TOKEN" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %} # GET Latest Updated Fixtures Returns you all fixtures that have received updates within 10 seconds. {% tabs %} {% tab title="Base URL" %} ```javascript https://api.sportmonks.com/v3/football/fixtures/latest ``` {% endtab %} {% tab title="Example Response" %} ```json { "data": [ { "id": 19238160, "sport_id": 1, "league_id": 1412, "season_id": 22988, "stage_id": 77469045, "group_id": null, "aggregate_id": null, "round_id": null, "state_id": 1, "venue_id": null, "name": "Tersana vs El Gounah", "starting_at": "2024-08-08 15:00:00", "result_info": null, "leg": "1/1", "details": null, "length": 90, "placeholder": false, "has_odds": true, "has_premium_odds": true, "starting_at_timestamp": 1723129200 }, { "id": 19238159, "sport_id": 1, "league_id": 1412, "season_id": 22988, "stage_id": 77469045, "group_id": null, "aggregate_id": null, "round_id": null, "state_id": 1, "venue_id": 4568, "name": "Pyramids FC vs Abu Qir Semad", "starting_at": "2024-08-08 15:00:00", "result_info": null, "leg": "1/1", "details": null, "length": 90, "placeholder": false, "has_odds": true, "has_premium_odds": true, "starting_at_timestamp": 1723129200 ``` {% endtab %} {% tab title="Field Description" %} | Field | Description | Type | | ------------- | ------------------------------------------------ | -------------- | | id | Refers the unique id of the fixture | integer | | sport\_id | Refers to the sport the fixture is played at | integer | | league\_id | Refers to the league the fixture is played in | integer | | season\_id | Refers to the seasons the fixture is played in | integer | | stage\_id | Refers to the stage the fixture is played in | integer | | group\_id | Refers to the group the fixture is played in | integer / null | | aggregate\_id | Refers to the aggregate the fixture is played at | integer / null | | state\_id | Refers to the state the fixture is played at | integer | | round\_id | Refers to the round the fixture is played at | integer / null | | state\_id | Refers to the state the fixture is played at | integer | | venue\_id | Refers to the venue the fixture is played at | integer / null | | name | Represents the name of the participants | string / null | | starting\_at | Datetime object representing the start time | date / null | | result\_info | Represents the final result info | string / null | | leg | Represents the leg of the fixture | string | | details | Represents details about the fixture | string / null | | length | Length of the fixture (minutes) | integer / null | | {% endtab %} | | | | {% endtabs %} | | | {% tabs %} {% tab title="Query Parameters" %}

Name	Required?	Description
`api_token`	YES Another option is to provide the API token in the header.	Your unique API token. Ex. ?api_token=YOUR_TOKEN
`include`	NO	Enrich the API response with more data by using includes. Ex. &include=participants;events
`select`	NO	Select specific fields on the base entity. Read how to select fields in our tutorial.
`sortBy`	NO	Order by specific fields on the base entity. For more information check out this page.
`filters`	NO	Filter the API response on multiple related entities. There are static filters and dynamic filters. Please find the possibilities in the Static and Dynamic Filter tab.
`locale`	NO	Translate name fields of the API Response in your selected language. Find more information and which languages are available on our translations page.

Static Filters	Available on Entity	Description	Example
`participantSearch`	Fixture	Filter on the matches of specific participants.	`&include=participants&filters=participantSearch:Celtic`
`todayDate`	Fixture	Filter all fixtures to find only the fixtures of today.	`&filters=todayDate`
`venues`	Fixture	Find all fixtures that are played in a specific venue.	`&include=venue&filters=venues:venueIDs` `&include=venue&filters=venues:10,12`
`Deleted`	Fixture	Filter on deleted fixtures only. This filter helps to keep your database in sync.	`&filters=Deleted`
`markets`	Odds	Filter the odds on a selection of markets separated by a comma.	`&include=odds&filters=markets:marketIDs` `&include=odds&filters=markets:12,14`
`bookmakers`	Odds	Filter the odds on a selection of bookmakers separated by a comma. (e.g: 2,14).	`&include=odds&filters=bookmakers:bookmakerIDs` `&include=odds&filters=bookmakers:2,14`
`WinningOdds`	Odds	Filter all winning odds.	`&include=odds&filters=WinningOdds`

{% endtab %} {% tab title="Dynamic Filters" %} The **dynamic filters** are based on entities and includes. Each dynamic filter uses an entity to filter on and one entity to apply the filter to. Below is an example with an explanation of how filters are set up. For more information, please look at our[ Filters page](/v3/api/request-options/filtering). {% hint style="info" %} Using an include? Check their respective filters on their entity page. For example if you use `&include=participants` you can apply [team-related filters](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#team). {% endhint %}

Dynamic Filters	Available on Entity	Description	Examples
`types`	Statistics, Events, Lineup, and way more. Check this endpoint for all possibilities.	Filter the statistics, events and more on a selection of type ids separated by a comma.	`&include=statistics.type&filters=fixturestatisticTypes:TypeIDs` `&include=statistics.type&filters=fixturestatisticTypes:42,49` `&include=events&filters=eventTypes:14` `&include=lineups.details.type&filters=lineupdetailTypes:118`
`states`	Fixtures Check this endpoint for all possibilities.	Filter the states of fixtures separated by a comma.	`&include=state&filters=fixtureStates:StateIDs` `&include=state&filters=fixtureStates:1`
`leagues`	Fixtures, Seasons, Standings, and way more. Check this endpoint for all possibilities.	Filter the fixtures based on leagues and their rounds.	`&filters=fixtureLeagues:leagueIDs` `&filters=fixtureLeagues:501,271`
`groups`	Fixtures, Standing, and more. Check this endpoint for all possibilities.	Filter the fixtures based on groups. Get their fixtures and standings.	`&include=group&filters=fixtureGroups:groupIDs` `&include=group&filters=fixtureGroups:246691`
`countries`	Coaches, Leagues, Players, Teams, and way more. Check this endpoint for all possibilities.	Filter the coaches, leagues, players and more based on countries.	`&include=coaches&filters=coachCountries:CountryIDs` `&include=coaches&filters=coachCountries:1161`
`seasons`	Statistics (players, team, coaches, referees), Standings, and way more. Check this endpoint for all possibilities.	Filter statistics, standings and topscorers based on seasons.	`&include=season.statistics&filters=seasonStatisticTypes:TypeIDs` `&include=season.statistics&filters=seasonStatisticTypes:52`

{% endtab %} {% endtabs %} ### Definition of “Latest Updated” This endpoint returns all fixtures whose livescore data has changed within the last 10 seconds. It tracks changes to these fields: state\_id, venue\_id, name, starting\_at, result\_info, leg, length, placeholder, has\_odds, has\_premium\_odds, and starting\_at\_timestamp. The update window is fixed at 10 seconds and cannot be altered. Changes to each field mean the following: * State\_id > the match phase progressed (for example, from 1 to 2 at kick-off or from 2 to 3 at half-time) * Venue\_id > the assigned venue was updated (for example, moved from stadium A to stadium B) * Name > the fixture name text was modified (for example, team abbreviations or formatting changed) * Starting\_at > the kick-off time string was rescheduled (for example, “2024-08-04 15:30:00” to “2024-08-04 16:00:00”) * Starting\_at\_timestamp > the UNIX timestamp for kick-off was rescheduled (for example, 1722785400 to 1722787200) * Result\_info > the score summary text was updated (for example, “0-0” to “1-0”) * Leg > the leg designation changed (for example, “1/2” to “2/2”) * Length > the fixture duration changed (for example, 90 to 120 when extra time is added) * Placeholder > whether the correct teams have been confirmed or not * Has\_odds > whether the match has odds available or not * Has\_premium\_odds > whether the match has premium odds available or not ### Frequency of updates & no-change responses On each call, any fixture that experienced a change to one or more of the tracked fields in the last 10 seconds will be returned in the data array.\ If no fixture changed during that window, the API returns HTTP 200 with "data": \[], signalling that there is nothing new to process. ### Polling frequency & rate limits * To reduce end-to-end latency, we highly recommend polling every 5 to 8 seconds if your rate limits allow. * Monitor for network jitter: slight timing shifts can cause overlap or small gaps. Adjust polling intervals if you see missed updates or duplicate data. ### Caching strategy & best practices * Cache only the tracked fields per fixture in a local store. * On each response: 1. Compare incoming values to your cache. 2. Discard fixtures with no differences. 3. Process fixtures with changes and update your cache entries. * Cache lookup data (such as team names and league info) locally, since it changes rarely. * If you encounter long runs of empty responses, back off on polling frequency or check for network issues to avoid unnecessary calls. ### **Filters** More information on how to use filters can be found in our tutorials on how to [filter](https://docs.sportmonks.com/football2/api/request-options/filtering). If you want more information on which filters to use, you can check out the following [endpoint](/v3/core-api/endpoints/filters/get-all-entity-filters): {% hint style="info" %} ```javascript https://api.sportmonks.com/v3/my/filters/entity?api_token=YOUR_TOKEN ``` {% endhint %} ### Pagination NO ### Include depth You can use a total of `3` nested includes on this endpoint ### Include options [`sport`](https://docs.sportmonks.com/v3/core-api/) [`round`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#round) [`stage`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#stage) [`group`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#group) [`aggregate`](/v3/endpoints-and-entities/entities/fixture#aggregate) [`league`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#league) [`season`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season)[`coaches`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#coach) [`tvStations`](/v3/endpoints-and-entities/entities/other#tvstation) [`venue`](/v3/endpoints-and-entities/entities/other#venue) [`state`](/v3/endpoints-and-entities/entities/other#state) [`weatherReport`](/v3/endpoints-and-entities/entities/other#weatherreport) [`lineups`](/v3/endpoints-and-entities/entities/fixture#lineup) [`events`](/v3/endpoints-and-entities/entities/fixture#event) [`timeline`](/v3/endpoints-and-entities/entities/fixture#event) [`comments`](/v3/endpoints-and-entities/entities/other#commentary) [`trends`](/v3/endpoints-and-entities/entities/statistic#trend) [`statistics`](/v3/endpoints-and-entities/entities/statistic#fixturestatistic) [`periods`](/v3/endpoints-and-entities/entities/fixture#period) [`participants` ](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#team)[`odds`](/v3/endpoints-and-entities/entities/odd-and-prediction#odd)[`premiumOdds`](https://docs.sportmonks.com/football/endpoints-and-entities/entities/odd-and-prediction#premium-odd) [`inplayOdds`](/v3/endpoints-and-entities/entities/odd-and-prediction#inplayodd) [`prematchNews`](/v3/endpoints-and-entities/entities/other#news) [`postmatchNews`](/v3/endpoints-and-entities/entities/other#news) [`metadata`](/v3/endpoints-and-entities/entities/other#metadata) [`sidelined`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#sidelined)[`predictions`](/v3/endpoints-and-entities/entities/odd-and-prediction#prediction-valuebet) [`referees`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#referees) [`formations`](/v3/endpoints-and-entities/entities/fixture#formation) [`ballCoordinates`](/v3/endpoints-and-entities/entities/fixture#ballcoordinate) [`scores`](/v3/endpoints-and-entities/entities/fixture#score) [`xGFixture`](/v3/endpoints-and-entities/entities/expected) [`pressure`](/v3/tutorials-and-guides/tutorials/includes/pressure-index) `expectedLineups` `predictedLineups` `matchfacts` `AIOverviews` ### **Related Entities:** Get an overview and explanation of all the fields returned in the API response. The related entities for the fixtures endpoints are: * [Fixture](/v3/endpoints-and-entities/entities/fixture#fixture) ### Postman We also offer detailed postman documentation with examples and a complete up-to-date version of all our endpoints. Below is a button that lets your fork the collection or import it. \ [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316?action=collection%2Ffork\&collection-url=entityId%3D11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316%26entityType%3Dcollection%26workspaceId%3D17c720d0-d97b-42a9-9ea7-23260ed53ddf) ### Code Example {% tabs %} {% tab title="Ruby" %} ```ruby require "uri" require "net/http" url = URI("https://api.sportmonks.com/v3/football/fixtures/latest?api_token=YOUR_TOKEN") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Get.new(url) response = https.request(request) puts response.read_body ``` {% endtab %} {% tab title="Python" %} ```python import http.client conn = http.client.HTTPSConnection("api.sportmonks.com") payload = '' headers = {} conn.request("GET", "/v3/football/fixtures/latest?api_token=YOUR_TOKEN", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) ``` {% endtab %} {% tab title="PHP" %} ```php 'https://api.sportmonks.com/v3/football/fixtures/latest?api_token=YOUR_TOKEN', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', )); $response = curl_exec($curl); curl_close($curl); echo $respons ``` {% endtab %} {% tab title="Java" %} ```java OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://api.sportmonks.com/v3/football/fixtures/latest?api_token=YOUR_TOKEN") .method("GET", null) .build(); Response response = client.newCall(request).execute(); ``` {% endtab %} {% tab title="Node.js" %} ``` var unirest = require('unirest'); var req = unirest('GET', 'https://api.sportmonks.com/v3/football/latest?api_token=YOUR_TOKEN') .end(function (res) { if (res.error) throw new Error(res.error); console.log(res.raw_body); }); ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://api.sportmonks.com/v3/football/fixtures/latest?api_token=YOUR_TOKEN" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %} # States Retrieve detailed states information of fixtures via one of our 2 states' endpoints. Per endpoint you can find the details including base URL, parameters, includes and more. * **GET All States:** returns all the states available within your subscription. * **GET State by ID:** returns state information from your requested state ID. ### Include options `none` ### **Related Entities:** Get an overview and explanation of all the fields returned in the API response. The related entities for the transfers' endpoints are: * [State](/v3/endpoints-and-entities/entities/other#state) ### **More information** {% content-ref url="/pages/Od0ztwiGCP7IvdnaGK88" %} [Types](/v3/definitions/types) {% endcontent-ref %} # GET All States Returns all states available within your subscription. {% tabs %} {% tab title="Base URL" %} ```javascript https://api.sportmonks.com/v3/football/states ``` {% endtab %} {% tab title="Example Response" %} ```json "data": [ { "id": 1, "state": "NS", "name": "Not Started", "short_name": "NS", "developer_name": "NS" }, { "id": 2, "state": "INPLAY_1ST_HALF", "name": "1st Half", "short_name": "1st", "developer_name": "INPLAY_1ST_HALF" }, { "id": 3, "state": "HT", "name": "Half Time", "short_name": "HT", "developer_name": "HT" }, { "id": 4, "state": "BREAK", "name": "Break", "short_name": "BRK", "developer_name": "BREAK" }, { "id": 5, "state": "FT", "name": "Full Time", "short_name": "FT", "developer_name": "FT" }, { "id": 6, "state": "INPLAY_ET", "name": "Extra Time", "short_name": "et", "developer_name": "INPLAY_ET" }, { "id": 7, "state": "AET", "name": "After Extra Time", "short_name": "AET", "developer_name": "AET" }, { "id": 8, "state": "FT_PEN", "name": "After Penalties", "short_name": "FTP", "developer_name": "FT_PEN" }, { "id": 9, "state": "INPLAY_PENALTIES", "name": "Penalties", "short_name": "PEN", "developer_name": "INPLAY_PENALTIES" }, { "id": 10, "state": "POSTPONED", "name": "Postponed", "short_name": "POST", "developer_name": "POSTPONED" }, ``` {% endtab %} {% tab title="Field Description" %} | Field | Description | Type | | --------------- | ---------------------------------------- | ------- | | id | Refers to the id of the state | integer | | state | Displays the state of the state | string | | name | Displays the full name of the state | string | | short\_name | Displays the short name of the state | string | | developer\_name | Displays the developer name of the state | string | | {% endtab %} | | | | {% endtabs %} | | | {% tabs %} {% tab title="Query Parameters" %}

Name	Required?	Description
`api_token`	YES Another option is to provide the API token in the header.	Your unique API token. Ex. ?api_token=YOUR_TOKEN
`include`	NO	Enrich the API response with more data by using includes. Ex. &include=participants;events
`select`	NO	Select specific fields on the base entity. Read how to select fields in our tutorial.
`filters`	NO	Filter the API response on multiple related entities. There are static filters and dynamic filters. Please find the possibilities in the Static and Dynamic Filter tab.
`locale`	NO	Translate name fields of the API Response in your selected language. Find more information and which languages are available on our translations page.

Static Filters	Available on Entity	Description	Example
N/A	N/A	Not available for this endpoint.	N/A

{% endtab %} {% tab title="Dynamic Filters" %} The **dynamic filters** are based on entities and includes. Each dynamic filter uses an entity to filter on and one entity to apply the filter on. Below are examples with explanations of how filters are set up. For more information, please look at our[ Filters page](/v3/api/request-options/filtering). {% hint style="info" %} Using an include? Check their respective filters on their entity page. For example if you use `&include=fixtures`, you can apply [fixture-related filters](/v3/endpoints-and-entities/entities/fixture#fixture-entity-filters). {% endhint %}

Dynamic Filters	Available on Entity	Description	Examples
N/A	N/A	Not available for this endpoint.	N/A

Parameter	Required	Description	Example
`order`	No	Returns states ordered by id (`asc` or `desc`). Defaults to asc	&order=desc
`per_page`	No	The amount of results to return per page (max 50.). Defaults to 25.	&per_page=30
`page`	No	You can paginate using the `has_more` parameter to determine if you can still propagate through the results.	&page=2

### Include depth You can use a total of `0` nested includes on this endpoint ### Include options `none` ### **Related Entities:** Get an overview and explanation of all the fields returned in the API response. The related entities for the transfers' endpoints are: * [State](/v3/endpoints-and-entities/entities/other#state) ### Postman We also offer detailed postman documentation with examples and a complete up-to-date version of all our endpoints. Below is a button that lets your fork the collection or import it. \ [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316?action=collection%2Ffork\&collection-url=entityId%3D11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316%26entityType%3Dcollection%26workspaceId%3D17c720d0-d97b-42a9-9ea7-23260ed53ddf) ### Code Example {% tabs %} {% tab title="Ruby" %} ```ruby require "uri" require "net/http" url = URI("https://api.sportmonks.com/v3/football/states?api_token=YOUR_TOKEN") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Get.new(url) response = https.request(request) puts response.read_body ``` {% endtab %} {% tab title="Python" %} ```python import http.client conn = http.client.HTTPSConnection("api.sportmonks.com") payload = '' headers = {} conn.request("GET", "/v3/football/states?api_token=YOUR_TOKEN", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) ``` {% endtab %} {% tab title="PHP" %} ```php 'https://api.sportmonks.com/v3/football/states?api_token=YOUR_TOKEN', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', )); $response = curl_exec($curl); curl_close($curl); echo $respons ``` {% endtab %} {% tab title="Java" %} ```java OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://api.sportmonks.com/v3/football/states?api_token=YOUR_TOKEN") .method("GET", null) .build(); Response response = client.newCall(request).execute(); ``` {% endtab %} {% tab title="Node.js" %} ``` var unirest = require('unirest'); var req = unirest('GET', 'https://api.sportmonks.com/v3/football/states?api_token=YOUR_TOKEN') .end(function (res) { if (res.error) throw new Error(res.error); console.log(res.raw_body); }); ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://api.sportmonks.com/v3/football/states?api_token=YOUR_TOKEN" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %} # GET State by ID Returns state information from your requested state ID. {% tabs %} {% tab title="Base URL" %} ```javascript https://api.sportmonks.com/v3/football/states/{ID} ``` {% endtab %} {% tab title="Example Response" %} ```json { "data": [ { "id": 5, "state": "FT", "name": "Full Time", "short_name": "FT", "developer_name": "FT", }, ``` {% endtab %} {% tab title="Field Description" %} | Field | Description | Type | | ------------- | ------------------------------------ | ------- | | id | Refers to the id of the state | integer | | state | Displays the state of the state | string | | name | Displays the full name of the state | string | | short\_name | Displays the short name of the state | string | | {% endtab %} | | | | {% endtabs %} | | | {% tabs %} {% tab title="Query Parameters" %}

Name	Required?	Description
`api_token`	YES Another option is to provide the API token in the header.	Your unique API token. Ex. ?api_token=YOUR_TOKEN
`include`	NO	Enrich the API response with more data by using includes. Ex. &include=participants;events
`select`	NO	Select specific fields on the base entity. Read how to select fields in our tutorial.
`filters`	NO	Filter the API response on multiple related entities. There are static filters and dynamic filters. Please find the possibilities in the Static and Dynamic Filter tab.
`locale`	NO	Translate name fields of the API Response in your selected language. Find more information and which languages are available on our translations page.

Static Filters	Available on Entity	Description	Example
N/A	N/A	Not available for this endpoint.	N/A

{% endtab %} {% tab title="Dynamic Filters" %} The **dynamic filters** are based on entities and includes. Each dynamic filter uses an entity to filter on and one entity to apply the filter on. Below are examples with explanations of how filters are set up. For more information, please look at our[ Filters page](/v3/api/request-options/filtering). {% hint style="info" %} Using an include? Check their respective filters on their entity page. For example if you use `&include=fixtures`, you can apply [fixture-related filters](/v3/endpoints-and-entities/entities/fixture#fixture-entity-filters). {% endhint %}

Dynamic Filters	Available on Entity	Description	Examples
N/A	N/A	Not available for this endpoint.	N/A

Lists the statistical groups the type may belong to.

Current available values are:
away, defensive, home, offensive, overall

| string\|null | | model\_type | Displays the model the type falls under | string | {% endtab %} {% endtabs %} {% tabs %} {% tab title="Query Parameters" %}

Name	Required?	Description
`api_token`	YES Another option is to provide the API token in the header.	Your unique API token. Ex. ?api_token=YOUR_TOKEN
`include`	NO	Enrich the API response with more data by using includes. Ex. &include=participants;events
`select`	NO	Select specific fields on the base entity. Read how to select fields in our tutorial.
`filters`	NO	Filter the API response on multiple related entities. There are static filters and dynamic filters. Please find the possibilities in the Static and Dynamic Filter tab.
`locale`	NO	Translate name fields of the API Response in your selected language. Find more information and which languages are available on our translations page.

Static Filters	Available on Entity	Description	Example
N/A	N/A	Not available for this endpoint.	N/A

{% endtab %} {% tab title="Dynamic Filters" %} The **dynamic filters** are based on entities and includes. Each dynamic filter uses an entity to filter on and one entity to apply the filter to. Below is an example with an explanation of how filters are set up. For more information, please look at our[ Filters page](/v3/api/request-options/filtering). {% hint style="info" %} Using an include? Check their respective filters on their entity page. For example if you use `&include=fixtures`, you can apply [fixture-related filters](/v3/endpoints-and-entities/entities/fixture#fixture-entity-filters). {% endhint %}

Dynamic Filters	Available on Entity	Description	Examples
N/A	N/A	Not available on this endpoint	N/A

Parameter	Required	Description	Example
`order`	No	Returns types ordered by id (`asc` or `desc`). Defaults to asc	&order=desc
`per_page`	No	The amount of results to return per page (max 50.). Defaults to 25.	&per_page=30
`page`	No	You can paginate using the `has_more` parameter to determine if you can still propagate through the results.	&page=2

**Include options** `None`**** **Related Entities:** Get an overview and explanation of all the fields returned in the API response. The related entities for the types' endpoints are: * [Type](https://docs.sportmonks.com/football2/v/core/entities/core#type) ### Postman We also offer detailed postman documentation with examples and a complete up-to-date version of all our endpoints. Below is a button that lets your fork the collection or import it. \ [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316?action=collection%2Ffork\&collection-url=entityId%3D11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316%26entityType%3Dcollection%26workspaceId%3D17c720d0-d97b-42a9-9ea7-23260ed53ddf) ### Code Example {% tabs %} {% tab title="Ruby" %} ```ruby require "uri" require "net/http" url = URI("https://api.sportmonks.com/v3/core/types?api_token=YOUR_TOKEN") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Get.new(url) response = https.request(request) puts response.read_body ``` {% endtab %} {% tab title="Python" %} ```python import http.client conn = http.client.HTTPSConnection("api.sportmonks.com") payload = '' headers = {} conn.request("GET", "/v3/core/types?api_token=YOUR_TOKEN", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) ``` {% endtab %} {% tab title="PHP" %} ```php 'https://api.sportmonks.com/v3/core/types?api_token=YOUR_TOKEN', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', )); $response = curl_exec($curl); curl_close($curl); echo $respons ``` {% endtab %} {% tab title="Java" %} ```java OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://api.sportmonks.com/v3/core/types?api_token=YOUR_TOKEN") .method("GET", null) .build(); Response response = client.newCall(request).execute(); ``` {% endtab %} {% tab title="Node.js" %} ``` var unirest = require('unirest'); var req = unirest('GET', 'https://api.sportmonks.com/v3/core/types?api_token=YOUR_TOKEN') .end(function (res) { if (res.error) throw new Error(res.error); console.log(res.raw_body); }); ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://api.sportmonks.com/v3/core/types?api_token=YOUR_TOKEN" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %} # GET Type by ID Returns all types available within your subscription. {% tabs %} {% tab title="Base URL" %} ```javascript https://api.sportmonks.com/v3/core/types/{typeID} ``` {% endtab %} {% tab title="Example Response" %} ```json { "data": { "id": 83, "name": "Redcards", "code": "redcards", "developer_name": "REDCARDS", "model_type": "statistic", "stat_group": "overall" }, ``` {% endtab %} {% tab title="Field Description" %} | Field | Description | Type | | --------------- | --------------------------------------- | ------- | | id | Refers to the id of the type | integer | | name | Displays the name of the type | string | | code | Displays the code of the type | string | | developer\_name | Displays the developer name of the type | string | | model\_type | Displays the model the type falls under | string | | {% endtab %} | | | | {% endtabs %} | | | {% tabs %} {% tab title="Query Parameters" %}

Name	Required?	Description
`api_token`	YES Another option is to provide the API token in the header.	Your unique API token. Ex. ?api_token=YOUR_TOKEN
`include`	NO	Enrich the API response with more data by using includes. Ex. &include=participants;events
`select`	NO	Select specific fields on the base entity. Read how to select fields in our tutorial.
`filters`	NO	Filter the API response on multiple related entities. There are static filters and dynamic filters. Please find the possibilities in the Static and Dynamic Filter tab.
`locale`	NO	Translate name fields of the API Response in your selected language. Find more information and which languages are available on our translations page.

Static Filters	Available on Entity	Description	Example
N/A	N/A	Not available for this endpoint.	N/A

{% endtab %} {% tab title="Dynamic Filters" %} The **dynamic filters** are based on entities and includes. Each dynamic filter uses an entity to filter on and one entity to apply the filter to. Below is an example with an explanation of how filters are set up. For more information, please look at our[ Filters page](/v3/api/request-options/filtering). {% hint style="info" %} Using an include? Check their respective filters on their entity page. For example if you use `&include=fixtures`, you can apply [fixture-related filters](/v3/endpoints-and-entities/entities/fixture#fixture-entity-filters). {% endhint %}

Dynamic Filters	Available on Entity	Description	Examples
N/A	N/A	Not available on this endpoint	N/A

{% endtab %} {% endtabs %} ### Filters More information on how to use filters can be found on our tutorials on how to [filter](https://docs.sportmonks.com/football2/api/request-options/filtering). If you want more information on which filters to use you can check out the following [endpoint](/v3/core-api/endpoints/filters/get-all-entity-filters): {% hint style="info" %} ```javascript https://api.sportmonks.com/v3/my/filters/entity?api_token=YOUR_TOKEN ``` {% endhint %} ### Pagination NO **Include options** `None`**** **Related Entities:** Get an overview and explanation of all the fields returned in the API response. The related entities for the types' endpoints are: * [Type](https://docs.sportmonks.com/football2/v/core/entities/core#type) ### Postman We also offer detailed postman documentation with examples and a complete up-to-date version of all our endpoints. Below is a button that lets your fork the collection or import it. \ [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316?action=collection%2Ffork\&collection-url=entityId%3D11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316%26entityType%3Dcollection%26workspaceId%3D17c720d0-d97b-42a9-9ea7-23260ed53ddf) ### Code Example {% tabs %} {% tab title="Ruby" %} ```ruby require "uri" require "net/http" url = URI("https://api.sportmonks.com/v3/core/types/{ID}?api_token=YOUR_TOKEN") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Get.new(url) response = https.request(request) puts response.read_body ``` {% endtab %} {% tab title="Python" %} ```python import http.client conn = http.client.HTTPSConnection("api.sportmonks.com") payload = '' headers = {} conn.request("GET", "/v3/core/types/{ID}?api_token=YOUR_TOKEN", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) ``` {% endtab %} {% tab title="PHP" %} ```php 'https://api.sportmonks.com/v3/core/types/{ID}?api_token=YOUR_TOKEN', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', )); $response = curl_exec($curl); curl_close($curl); echo $respons ``` {% endtab %} {% tab title="Java" %} ```java OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://api.sportmonks.com/v3/core/types/{ID}?api_token=YOUR_TOKEN") .method("GET", null) .build(); Response response = client.newCall(request).execute(); ``` {% endtab %} {% tab title="Node.js" %} ``` var unirest = require('unirest'); var req = unirest('GET', 'https://api.sportmonks.com/v3/core/types/{ID}?api_token=YOUR_TOKEN') .end(function (res) { if (res.error) throw new Error(res.error); console.log(res.raw_body); }); ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://api.sportmonks.com/v3/core/types/{ID}?api_token=YOUR_TOKEN" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %} # GET Type by Entity Returns types which are available per entity. {% tabs %} {% tab title="Base URL" %} ```javascript https://api.sportmonks.com/v3/core/types/entities ``` {% endtab %} {% tab title="Example Response" %} ```json { "data": { "CoachStatisticDetail": { "updated_at": "2023-06-30T12:00:31.000000Z", "types": [ { "id": 59, "name": "Substitutions", "code": "substitutions", "developer_name": "SUBSTITUTIONS", "model_type": "statistic", "stat_group": "overall" }, { "id": 83, "name": "Redcards", "code": "redcards", "developer_name": "REDCARDS", "model_type": "statistic", "stat_group": "overall" }, { "id": 84, "name": "Yellowcards", "code": "yellowcards", "developer_name": "YELLOWCARDS", "model_type": "statistic", "stat_group": "overall" }, ``` {% endtab %} {% tab title="Field Description" %} | Field | Description | Type | | --------------- | -------------------------------------------- | ------- | | updated\_at | Refers to the time the type was last updated | string | | id | Refers to the id of the type | integer | | name | Displays the name of the type | string | | code | Displays the code of the type | string | | developer\_name | Displays the developer name of the type | string | | model\_type | Displays the model\_type of the type | string | | stat\_group | Displays the stat group of the type | string | | {% endtab %} | | | | {% endtabs %} | | | #### Parameters

Name	Required?	Description
`api_token`	YES Another option is to provide the API token in the header.	Your unique API token. Ex. ?api_token=YOUR_TOKEN
`include`	NO	Enrich the API response with more data by using includes. Ex. &include=participants;events
`select`	NO	Select specific fields on the base entity. Read how to select fields in our tutorial.
`filters`	NO	Filter the API response on multiple related entities. There are static filters and dynamic filters. Please find the possibilities in the Static and Dynamic Filter tab.
`locale`	NO	Translate name fields of the API Response in your selected language. Find more information and which languages are available on our translations page.

#### Pagination No #### Include options Using includes is **disabled** for this endpoint. **Related Entities:** Get an overview and explanation of all the fields returned in the API response. The related entities for the cities' endpoints are: * [Type](https://docs.sportmonks.com/football/v/core-api/entities/core#type) #### Code Example {% tabs %} {% tab title="Ruby" %} ```ruby require "uri" require "net/http" url = URI("https://api.sportmonks.com/v3/core/types/1?api_token={your_token}") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Get.new(url) response = https.request(request) puts response.read_body ``` {% endtab %} {% tab title="Python" %} ```python import http.client conn = http.client.HTTPSConnection("api.sportmonks.com") payload = '' headers = {} conn.request("GET", "/v3/core/types/1?api_token={your_token}", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) ``` {% endtab %} {% tab title="PHP" %} ```php 'https://api.sportmonks.com/v3/core/types/1?api_token={your_token}', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', )); $response = curl_exec($curl); curl_close($curl); echo $respons ``` {% endtab %} {% tab title="Java" %} ```java OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://api.sportmonks.com/v3/core/types/1?api_token={your_token}") .method("GET", null) .build(); Response response = client.newCall(request).execute(); ``` {% endtab %} {% tab title="Node.js" %} ``` var unirest = require('unirest'); var req = unirest('GET', 'https://api.sportmonks.com/v3/core/types/1?api_token={your_token}') .end(function (res) { if (res.error) throw new Error(res.error); console.log(res.raw_body); }); ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://api.sportmonks.com/v3/core/types/1?api_token={your_token}" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %} # Leagues Access comprehensive league data through the Sportmonks Football API. The Leagues endpoints provide information about domestic and international football competitions. Overview Every continent has countries, every country has one or multiple leagues, and every league has one or more seasons. For most applications, the leagues endpoint serves as the starting point for accessing football data. Use these endpoints to gather complete overviews of all available leagues within your subscription, retrieve basic league information, or enrich your response with season and fixture data. ### Available Endpoints There are 6 league endpoints available, each serving specific use cases: * [**GET All Leagues**](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/leagues/get-all-leagues): Returns all leagues accessible within your subscription * [**GET League by ID**](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/leagues/get-league-by-id): Returns a single league by its unique identifier * [**GET Leagues by Live**](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/leagues/get-leagues-by-live): Returns leagues currently with live fixtures * [**GET Leagues by Fixture Date**](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/leagues/get-leagues-by-fixture-date): Returns leagues with fixtures on a specific date * [**GET Leagues by Country ID**](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/leagues/get-leagues-by-country-id): Returns all leagues from a specific country * [**GET Leagues Search by Name**](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/leagues/get-leagues-search-by-name): Returns leagues matching your search query

### Understanding league structures Football leagues have fundamentally different organisational structures depending on the competition type. Understanding these structures is crucial for correctly requesting and displaying data such as standings, fixtures, and statistics. #### The hierarchy Every league follows a hierarchical structure: ``` League └── Season (e.g., "2025/2026") └── Stage(s) (e.g., "Regular Season", "Group Stage", "Quarter-finals") └── Round(s) (e.g., "Round 1", "Round 2", "Matchweek 15") └── Group(s) (optional - e.g., "Group A", "Group B") └── Fixtures (individual matches) ``` **Key components:** * **League**: The competition itself (e.g., Premier League, Champions League) * **Season**: A specific edition of the league (e.g., 2024/2025, 2023/2024) * **Stage**: A distinct phase within a season (e.g., "Regular Season", "Playoffs", "Group Stage", "Semi-finals") * **Round**: A specific matchday or game week within a stage * **Group**: Optional groupings within stages (used in tournaments with group phases) * **Fixture**: An individual match between two teams ### League classification by structure Different leagues are organized in distinct ways. Here's how to identify and work with each structure type: #### 1. Simple domestic leagues **Characteristics:** * Single "Regular Season" stage * Round-robin format where every team plays every other team twice (home and away) * Sequential rounds representing match weeks * One unified standings table **Stage type:** Group stage (type\_id: 223) **Examples:** English Premier League, La Liga, Serie A, Bundesliga **Structure:** ``` League: English Premier League (league_id: 8) └── Season: 2025/2026 └── Stage: "Regular Season" (Group Stage) └── Rounds: 1, 2, 3... up to 38 ``` **API request example:** ```http GET /v3/football/leagues/8?api_token=YOUR_TOKEN&include=currentSeason.stages ``` **Response example:** ```json { "data": { "id": 8, "sport_id": 1, "country_id": 462, "name": "Premier League", "active": true, "short_code": "UK PL", "image_path": "https:\/\/cdn.sportmonks.com\/images\/soccer\/leagues\/8\/8.png", "type": "league", "sub_type": "domestic", "last_played_at": "2025-11-24 20:00:00", "category": 1, "has_jerseys": false, "currentseason": { "id": 25583, "sport_id": 1, "league_id": 8, "tie_breaker_rule_id": 1526, "name": "2025\/2026", "finished": false, "pending": false, "is_current": true, "starting_at": "2025-08-15", "ending_at": "2026-05-24", "standings_recalculated_at": "2025-11-24 22:00:53", "games_in_current_week": true, "stages": [ { "id": 77476879, "sport_id": 1, "league_id": 8, "season_id": 25583, "type_id": 223, "name": "Regular Season", "sort_order": 1, "finished": false, "is_current": true, "starting_at": "2025-08-15", "ending_at": "2026-05-24", "games_in_current_week": false, "tie_breaker_rule_id": null } ] } }, } ``` **Key observations:** * Only one stage for the entire season (typical for simple domestic leagues) * The stage type is Group Stage (type\_id: 223), which indicates a round-robin format with standings * 38 rounds represent the complete double round-robin schedule (20 teams × 2 = 38 matches per team) * To access the league table, use the standings endpoint with the season\_id: `/v3/football/standings/seasons/25583` #### 2. Multi-phase domestic leagues **Characteristics:** * Multiple sequential stages within a single season * Each phase may have different structures or participant configurations * Common in leagues that split into championship and relegation groups **Stage types:** Multiple Group Stages (type\_id: 223) **Example:** Liga Profesional de Fútbol (Argentina) **Structure:** ``` League: Argentine Liga Profesional (league_id: 636) └── Season: 2025 (season_id: 24969) ├── Stage: "1st Phase" (Group Stage - type_id: 223) │ └── Group rounds with all teams ├── Stage: "1st Phase - 8th Finals" (Knock Out - type_id: 224) ├── Stage: "1st Phase - Quarter-finals" (Knock Out - type_id: 224) ├── Stage: "1st Phase - Semi-finals" (Knock Out - type_id: 224) ├── Stage: "1st Phase - Final" (Knock Out - type_id: 224) ├── Stage: "2nd Phase" (Group Stage - type_id: 223) │ └── Group rounds with all teams ├── Stage: "2nd Phase - 8th Finals" (Knock Out - type_id: 224) ├── Stage: "2nd Phase - Quarter-finals" (Knock Out - type_id: 224) ├── Stage: "2nd Phase - Semi-finals" (Knock Out - type_id: 224) └── Stage: "2nd Phase - Final" (Knock Out - type_id: 224) ``` **API request example:** ```http GET /v3/football/leagues/636?api_token=YOUR_TOKEN&include=currentSeason.stages ``` **Response example:** ```json { "data": { "id": 636, "name": "Liga Profesional de Fútbol", "type": "league", "sub_type": "domestic", "currentSeason": { "data": { "id": 24969, "name": "2025", "stages": { "data": [ { "id": 77475076, "name": "1st Phase", "type_id": 223, "sort_order": 1, "finished": true, "is_current": false }, { "id": 77475075, "name": "1st Phase - 8th Finals", "type_id": 224, "sort_order": 2, "finished": true, "is_current": false }, { "id": 77475074, "name": "1st Phase - Quarter-finals", "type_id": 224, "sort_order": 3, "finished": true, "is_current": false }, { "id": 77475073, "name": "1st Phase - Semi-finals", "type_id": 224, "sort_order": 4, "finished": true, "is_current": false }, { "id": 77475072, "name": "1st Phase - Final", "type_id": 224, "sort_order": 5, "finished": true, "is_current": false }, { "id": 77475071, "name": "2nd Phase", "type_id": 223, "sort_order": 6, "finished": true, "is_current": false }, { "id": 77475070, "name": "2nd Phase - 8th Finals", "type_id": 224, "sort_order": 7, "finished": false, "is_current": true }, { "id": 77475069, "name": "2nd Phase - Quarter-finals", "type_id": 224, "sort_order": 8, "finished": false, "is_current": false }, { "id": 77475068, "name": "2nd Phase - Semi-finals", "type_id": 224, "sort_order": 9, "finished": false, "is_current": false }, { "id": 77475067, "name": "2nd Phase - Final", "type_id": 224, "sort_order": 10, "finished": false, "is_current": false } ] } } } } } ``` **Key observations:** * Multiple stages exist within one season * `sort_order` indicates the sequence of stages * `is_current: true` shows which stage is actively being played * After the 1st Phase concludes, teams progress to different groups based on their standings #### 3. International cup tournaments **Characteristics:** * Multiple stages with different types (Qualifying, Group Stage, Knockout) * Groups within the Group Stage * Progressive elimination format * Complex structure spanning multiple competition phases **Stage types:** Qualifying (type\_id: 225), Group Stage (type\_id: 223), Knock Out (type\_id: 224) **Examples:** UEFA Champions League, FIFA World Cup, Copa Libertadores, UEFA Europa League **Structure:** ``` League: UEFA Champions League (league_id: 2) └── Season: 2025/2026 (season_id: 25580) ├── Stage: "Qualification Round 1" (Qualifying - type_id: 225) ├── Stage: "Qualification Round 2" (Qualifying - type_id: 225) ├── Stage: "Qualification Round 3" (Qualifying - type_id: 225) ├── Stage: "Play-offs" (Qualifying - type_id: 225) ├── Stage: "League Stage" (Group Stage - type_id: 223) │ └── Rounds: 1, 2, 3, 4, 5, 6, 7, 8 ├── Stage: "Knockout Round Play-offs" (Knock Out - type_id: 224) ├── Stage: "8th Finals" (Knock Out - type_id: 224) ├── Stage: "Quarter-finals" (Knock Out - type_id: 224) ├── Stage: "Semi-finals" (Knock Out - type_id: 224) └── Stage: "Final" (Knock Out - type_id: 224) ``` **API request example:** ```http GET /v3/football/leagues/2?api_token=YOUR_TOKEN&include=currentSeason.stages ``` **Response example:** ```json { "data": { "id": 2, "sport_id": 1, "country_id": 41, "name": "Champions League", "active": true, "short_code": "UEFA CL", "image_path": "https:\/\/cdn.sportmonks.com\/images\/soccer\/leagues\/2.png", "type": "league", "sub_type": "cup_international", "last_played_at": "2025-11-25 20:00:00", "category": 1, "has_jerseys": false, "currentseason": { "id": 25580, "sport_id": 1, "league_id": 2, "tie_breaker_rule_id": 33094, "name": "2025\/2026", "finished": false, "pending": false, "is_current": true, "starting_at": "2025-07-08", "ending_at": "2026-01-28", "standings_recalculated_at": "2025-11-25 22:05:19", "games_in_current_week": true, "stages": [ { "id": 77477731, "sport_id": 1, "league_id": 2, "season_id": 25580, "type_id": 225, "name": "Play-offs", "sort_order": 4, "finished": true, "is_current": false, "starting_at": "2025-08-19", "ending_at": "2025-08-27", "games_in_current_week": false, "tie_breaker_rule_id": null }, { "id": 77478049, "sport_id": 1, "league_id": 2, "season_id": 25580, "type_id": 223, "name": "League Stage", "sort_order": 5, "finished": false, "is_current": true, "starting_at": "2025-09-16", "ending_at": "2026-01-28", "games_in_current_week": false, "tie_breaker_rule_id": null }, { "id": 77476876, "sport_id": 1, "league_id": 2, "season_id": 25580, "type_id": 225, "name": "Qualification Round 1", "sort_order": 1, "finished": true, "is_current": false, "starting_at": "2025-07-08", "ending_at": "2025-07-16", "games_in_current_week": false, "tie_breaker_rule_id": null }, { "id": 77476881, "sport_id": 1, "league_id": 2, "season_id": 25580, "type_id": 225, "name": "Qualification Round 2", "sort_order": 2, "finished": true, "is_current": false, "starting_at": "2025-07-22", "ending_at": "2025-07-30", "games_in_current_week": false, "tie_breaker_rule_id": null }, { "id": 77477369, "sport_id": 1, "league_id": 2, "season_id": 25580, "type_id": 225, "name": "Qualification Round 3", "sort_order": 3, "finished": true, "is_current": false, "starting_at": "2025-08-05", "ending_at": "2025-08-12", "games_in_current_week": false, "tie_breaker_rule_id": null } ] } } } ``` *** #### 4. Domestic cup competitions **Characteristics:** * Knockout-only format (no league table) * Progressive rounds of elimination * Single or two-legged ties **Stage type:** Knock Out (type\_id: 224) **Examples:** FA Cup, Copa del Rey, DFB Pokal, Coppa Italia **Structure:** ``` League: FA Cup (league_id: 24) └── Season: 2025/2026 (season_id: 25567) ├── Stage: "1st Round Qualifying" (Knock Out - type_id: 224) ├── Stage: "2nd Round Qualifying" (Knock Out - type_id: 224) ├── Stage: "3rd Round Qualifying" (Knock Out - type_id: 224) ├── Stage: "4th Round Qualifying" (Knock Out - type_id: 224) ├── Stage: "1st Round" (Knock Out - type_id: 224) ├── Stage: "2nd Round" (Knock Out - type_id: 224) ├── Stage: "3rd Round" (Knock Out - type_id: 224) ├── Stage: "4th Round" (Knock Out - type_id: 224) ├── Stage: "5th Round" (Knock Out - type_id: 224) ├── Stage: "Quarter-finals" (Knock Out - type_id: 224) ├── Stage: "Semi-finals" (Knock Out - type_id: 224) └── Stage: "Final" (Knock Out - type_id: 224) ``` ```http GET /v3/football/leagues/24?api_token=YOUR_TOKEN&include=currentSeason.stages ``` **Response example:** ```json { "data": { "id": 24, "sport_id": 1, "country_id": 462, "name": "FA Cup", "active": true, "short_code": "UK FA Cup", "image_path": "https:\/\/cdn.sportmonks.com\/images\/soccer\/leagues\/24\/24.png", "type": "league", "sub_type": "domestic_cup", "last_played_at": "2025-11-03 19:30:00", "category": 2, "has_jerseys": false, "currentseason": { "id": 25919, "sport_id": 1, "league_id": 24, "tie_breaker_rule_id": 171, "name": "2025\/2026", "finished": false, "pending": false, "is_current": true, "starting_at": "2025-08-01", "ending_at": "2025-09-30", "standings_recalculated_at": null, "games_in_current_week": true, "stages": [ { "id": 77477926, "sport_id": 1, "league_id": 24, "season_id": 25919, "type_id": 225, "name": "1st Round Qualifying", "sort_order": 5, "finished": true, "is_current": false, "starting_at": "2025-08-29", "ending_at": "2025-09-03", "games_in_current_week": false, "tie_breaker_rule_id": null }, { "id": 77477864, "sport_id": 1, "league_id": 24, "season_id": 25919, "type_id": 225, "name": "Preliminary Round Replays", "sort_order": 4, "finished": true, "is_current": false, "starting_at": "2025-08-18", "ending_at": "2025-08-26", "games_in_current_week": false, "tie_breaker_rule_id": null }, { "id": 77478105, "sport_id": 1, "league_id": 24, "season_id": 25919, "type_id": 224, "name": "2nd Round Qualifying", "sort_order": 6, "finished": true, "is_current": false, "starting_at": "2025-09-12", "ending_at": "2025-09-23", "games_in_current_week": false, "tie_breaker_rule_id": null }, { "id": 77478660, "sport_id": 1, "league_id": 24, "season_id": 25919, "type_id": 224, "name": "Round 1", "sort_order": 4, "finished": true, "is_current": false, "starting_at": "2025-10-31", "ending_at": "2025-11-03", "games_in_current_week": false, "tie_breaker_rule_id": null }, { "id": 77478863, "sport_id": 1, "league_id": 24, "season_id": 25919, "type_id": 224, "name": "Round 2", "sort_order": 7, "finished": false, "is_current": false, "starting_at": "2025-12-05", "ending_at": "2025-12-08", "games_in_current_week": false, "tie_breaker_rule_id": null }, { "id": 77478288, "sport_id": 1, "league_id": 24, "season_id": 25919, "type_id": 225, "name": "3rd Round Qualifying", "sort_order": 7, "finished": true, "is_current": false, "starting_at": "2025-09-27", "ending_at": "2025-09-30", "games_in_current_week": false, "tie_breaker_rule_id": null }, { "id": 77477212, "sport_id": 1, "league_id": 24, "season_id": 25919, "type_id": 225, "name": "Extra Preliminary Round", "sort_order": 1, "finished": true, "is_current": false, "starting_at": "2025-08-01", "ending_at": "2025-08-03", "games_in_current_week": false, "tie_breaker_rule_id": null }, { "id": 77477213, "sport_id": 1, "league_id": 24, "season_id": 25919, "type_id": 225, "name": "Preliminary Round", "sort_order": 3, "finished": true, "is_current": false, "starting_at": "2025-08-15", "ending_at": "2025-08-19", "games_in_current_week": false, "tie_breaker_rule_id": null }, { "id": 77477536, "sport_id": 1, "league_id": 24, "season_id": 25919, "type_id": 224, "name": "Extra Preliminary Round Replays", "sort_order": 2, "finished": true, "is_current": false, "starting_at": "2025-08-04", "ending_at": "2025-08-12", "games_in_current_week": false, "tie_breaker_rule_id": null }, { "id": 77478393, "sport_id": 1, "league_id": 24, "season_id": 25919, "type_id": 225, "name": "Qualification Round 4", "sort_order": 4, "finished": true, "is_current": false, "starting_at": "2025-10-11", "ending_at": "2025-10-14", "games_in_current_week": false, "tie_breaker_rule_id": null } ] } }, } ``` *** #### 5. Play-off competitions **Characteristics:** * Post-season tournaments * Determine promotion, relegation, or championship * Often part of a larger league system **Stage types:** Qualifying (type\_id: 225) or Knock Out (type\_id: 224) **Examples:** Various promotion/relegation playoffs, championship playoffs **Structure:** ``` League: Playoff Competition └── Season: 2025/2026 ├── Stage: "Semi-finals" (Knock Out) └── Stage: "Final" (Knock Out) ``` *** ### Stage Types Reference The API uses three main stage types to classify different phases of competitions: | Type ID | Type Name | Description | Typical Use | | ------- | --------------- | ---------------------------------------------------------------------- | --------------------------------------------------------- | | **223** | **Group Stage** | Round-robin format where teams play within a group or league structure | Regular seasons, group phases in tournaments | | **224** | **Knock Out** | Elimination format where losing teams are eliminated | Cup rounds, tournament knockout phases | | **225** | **Qualifying** | Preliminary rounds to determine tournament participants | Qualification rounds, playoffs for main competition entry | *** ### League types and Sub-types Leagues are classified by type and sub-type to help identify their nature: #### League Types * **League**: A standard league competition * **Phase**: A specific phase within a league structure #### League Sub-types | Sub-type | Description | Examples | | ---------------------- | ------------------------------------ | ------------------------------------------------------------ | | D**omestic** | A league within one country | English Premier League, Serie A, La Liga, Bundesliga | | D**omestic\_cup** | A cup competition within one country | FA Cup, DFB Pokal, Coppa Italia, Copa del Rey | | I**nternational** | A league for international teams | FIFA World Cup, European Championship, Copa America | | C**up\_international** | An international cup competition | UEFA Champions League, Copa Libertadores, UEFA Europa League | | P**lay-offs** | A playoff competition | Various promotion/relegation playoffs | | F**riendly** | Friendly matches | Club Friendlies, International Friendlies | *** ### Practical use cases Understanding league structures is essential for: #### 1. Requesting standings correctly **Simple league:** ```http GET /v3/football/standings/seasons/23690?api_token=YOUR_TOKEN # Returns one unified league table ``` **Tournament with groups:** ```http GET /v3/football/standings/seasons/23456?api_token=YOUR_TOKEN # Returns multiple group tables (Group A, B, C, etc.) ``` #### 2. Determining current competition phase Check the `is_current` field on stages to identify which phase is active: ```http GET /v3/football/seasons/8?api_token=YOUR_TOKEN&include=stages ``` Look for `"is_current": true` to find the active stage. #### 3. Understanding round structure Different leagues have different round structures based on their format: **Simple domestic leagues:** * **Premier League** (league\_id: 8): 38 rounds (20 teams playing home and away) * **La Liga** (league\_id: 564): 38 rounds (20 teams playing home and away) * **Bundesliga** (league\_id: 82): 34 rounds (18 teams playing home and away) **Multi-phase domestic leagues:** * **Argentine Liga Profesional** (league\_id: 636): * 1st Phase: 27 rounds (group stage) * 1st Phase Playoffs: Multiple knockout rounds (8th Finals → Quarter-finals → Semi-finals → Final) * 2nd Phase: 27 rounds (group stage) * 2nd Phase Playoffs: Multiple knockout rounds (8th Finals → Quarter-finals → Semi-finals → Final) **International cup tournaments:** * **Champions League** (league\_id: 2): * Qualification Rounds: 2-leg ties per round * League Stage: 8 rounds (single round-robin format, new in 2024/25) * Knockout stages: Typically 2-leg ties per round (except Final which is single match) **Domestic cup competitions:** * **FA Cup** (league\_id: 20): Each stage is a single elimination round (single match with potential replays in early rounds) * **Copa del Rey**: Earlier rounds single-leg, later rounds typically two-leg ties **Play-off competitions:** * **Championship Playoff** (league\_id: 1371): * Semi-finals: 2-leg ties * Final: Single match at neutral venue #### 4. Filtering fixtures by stage When requesting fixtures, you can filter by specific stages using the `stage_id`: **Example 1: Get fixtures from a specific stage** ```http GET /v3/football/fixtures/between/{start_date}/{end_date} ?api_token=YOUR_TOKEN&filters=fixtureStages:77478049 ``` Returns only fixtures from Champions League "League Stage" (stage\_id: 77478049) **Example 2: Get current stage fixtures for a league** ```http GET /v3/football/leagues/636?api_token=YOUR_TOKEN&include=currentSeason.stages ``` First, identify the current stage (where `is_current: true`), then use that `stage_id` to filter fixtures. **Example 3: Get fixtures from multiple stages** ```bash GET /v3/football/fixtures/between/2025-11-01/2025-11-30 ?api_token=YOUR_TOKEN&filters=fixtureStages:77475070,77475069 ``` Returns fixtures from both "2nd Phase - 8th Finals" and "2nd Phase - Quarter-finals" stages of Argentine Liga Profesional. **Example 4: Get all fixtures for a specific season** ```http GET /v3/football/fixtures/seasons/25583?api_token=YOUR_TOKEN ``` Returns all fixtures across all stages for Premier League 2025/2026 season. **Practical workflow:** 1. Query the league to get current season and stages 2. Identify the stage\_id you need (using `is_current`, `finished`, or `name`) 3. Use that stage\_id in your fixtures filter 4. Combine with date ranges for more precise results #### 5. Checking if standings are available Not all stages have standings tables. To determine if standings data exists for a stage: **Check stage type\_id** * **Group Stage** (type\_id: 223) → Usually has standings tables * **Knock Out** (type\_id: 224) → No standings tables * **Qualifying** (type\_id: 225) → May or may not have standings (verify with API) *** ### Tips for working with different structures #### Always check stages first Before requesting data, understand the league structure: ```bash GET /v3/football/leagues/{league_id}?api_token=YOUR_TOKEN&include=currentSeason.stages ``` This reveals: * How many stages exist * What type each stage is (type\_id: 223, 224, or 225) * Which stage is currently active (`is_current: true`) * Stage progression order (`sort_order`) #### Use `sort_order` for stage progression The `sort_order` field indicates the sequence of stages. Lower numbers occur first, higher numbers occur later in the season. #### Groups within stages Some tournaments have groups within stages. Check for `group_id` in fixtures to identify group memberships: ```bash GET /v3/football/fixtures/18535517?api_token=YOUR_TOKEN ``` If `"group_id": 244365`, this fixture belongs to a specific group (e.g., Group A). #### Monitor `is_current` for active stages The `is_current` field tells you which stage is actively being played. This is crucial for displaying current standings and fixtures. ### Common include options Enrich your league requests with additional data: | Include | Description | | --------------- | ------------------------------------ | | `sport` | Sport information | | `country` | Country details | | `stages` | All stages within the current season | | `currentSeason` | Active season information | | `seasons` | Historical seasons | | `latest` | Most recent fixture | | `upcoming` | Next scheduled fixture | | `inplay` | Currently live fixtures | | `today` | Today's fixtures | **Example:** ```http GET /v3/football/leagues/501?api_token=YOUR_TOKEN&include=currentSeason.stages ``` This returns the league with its current season and all stages. **To get rounds, make a separate request:** ```http GET /v3/football/stages/{stage_id}?api_token=YOUR_TOKEN&include=rounds ``` Or retrieve rounds for all stages in a season: ```http GET /v3/football/seasons/25598?api_token=YOUR_TOKEN&include=stages.rounds ``` **Note:** The API limits nested includes to 2 levels maximum. You cannot use `currentSeason.stages.rounds` in a single request. Instead, use separate requests or structure your includes to stay within the 2-level limit (e.g., `stages.rounds` when querying a season directly). ### Related entities For complete field descriptions and available includes, see: * League, Season, Schedule, Stage and Round Entity Documentation * Stages Endpoint Documentation * Rounds Endpoint Documentation * Standings Documentation ### Need Help? If you have questions about league structures or need assistance implementing league data in your application, contact our support team at . # GET All Leagues Returns all the leagues available within your subscription {% tabs %} {% tab title="Base URL" %} ```javascript https://api.sportmonks.com/v3/football/leagues ``` {% endtab %} {% tab title="Example Response" %} ```json { "data": [ { "id": 271, "sport_id": 1, "country_id": 320, "name": "Superliga", "active": true, "short_code": "DNK SL", "image_path": "https://cdn.sportmonks.com/images/soccer/leagues/271.png", "type": "league", "sub_type": "domestic", "last_played_at": "2024-08-05 17:00:00", "category": 2, "has_jerseys": false }, { "id": 501, "sport_id": 1, "country_id": 1161, "name": "Premiership", "active": true, "short_code": "SCO P", "image_path": "https://cdn.sportmonks.com/images/soccer/leagues/501.png", "type": "league", "sub_type": "domestic", "last_played_at": "2024-08-05 19:00:00", "category": 2, "has_jerseys": false ``` {% endtab %} {% tab title="Field Description" %}

Field	Description	Type
id	Refers to the unique id of th league	integer
sport_id	Refers to the sport of the league	integer
country_id	Refers to the country of the league	integer
name	The name of the league	string
active	Indicates if the league is active or inactive	integer
short_code	The short code of the league	string / null
image_path	Image path to the league logo	string
type	Indicates the type of the league	string
sub_type	Indicates the subtype of the league	string
last_played_at	The date of when the last fixture was played in the league	string
category	Indicates the category of the league	integer

{% endtab %} {% endtabs %} {% tabs %} {% tab title="Query parameters" %}

Name	Required?	Description
`api_token`	YES Another option is to provide the API token in the header.	Your unique API token. Ex. ?api_token=YOUR_TOKEN
`include`	NO	Enrich the API response with more data by using includes. Ex. &include=participants;events
`select`	NO	Select specific fields on the base entity. Read how to select fields in our tutorial.
`filters`	NO	Filter the API response on multiple related entities. There are static filters and dynamic filters. Please find the possibilities in the Static and Dynamic Filter tab.
`locale`	NO	Translate name fields of the API Response in your selected language. Find more information and which languages are available on our translations page.

{% endtab %} {% tab title="Static filters" %} **Static filters** are always the same and filter in one specific way without any custom options. Each static filter is listed below and has a description of how it filters. For more information, please look at our[ Filters page](/v3/api/request-options/filtering).

Static filters	Available on Entity	Description	Example
`IdAfter`	All	Filter all leagues starting from a certain league ID.	`&filters=IdAfter:leagueID` `&filters=IdAfter:12`

{% endtab %} {% tab title="Dynamic filters" %} The **dynamic filters** are based on entities and includes. Each dynamic filter uses an entity to filter on and one entity to apply the filter on. Below are examples with explanations of how filters are set up. For more information, please look at our[ Filters page](/v3/api/request-options/filtering). {% hint style="info" %} Using an include? Check their respective filters on their entity page. For example if you use `&include=fixtures`, you can apply [fixture-related filters](/v3/endpoints-and-entities/entities/fixture#fixture-entity-filters). {% endhint %}

Dynamic filters	Available on Entity	Description	Example
`countries`	Coaches, Leagues, Players, Teams, and way more. Check this endpoint for all possibilities.	Filter the leagues based on countries.	`&include=country&filters=leagueCountries:countryIDs` `&include=country&filters=leagueCountries:41`
`seasons`	Statistics (players, team, coaches, referees), Standings, and way more. Check this endpoint for all possibilities.	Filter statistics, standings and topscorers based on seasons.	`&include=seasons.statistics&filters=seasonStatisticTypes:TypeIDs` `&include=seasons.statistics&filters=seasonStatisticTypes:52`
`types`	Statistics, Events, Lineup, and way more. Check this endpoint for all possibilities.	Filter the league stages on a selection of type ID's separated by a comma.	`&include=stages.type&filters=stageTypes:TypeIDs` `&include=stages.type&filters=stageTypes:224`

Parameter	Required	Description	Example
`order`	No	Returns leagues ordered by id (`asc` or `desc`). Defaults to asc	&order=desc
`per_page`	No	The amount of results to return per page (max 50.). Defaults to 25.	&per_page=30
`page`	No	You can paginate using the `has_more` parameter to determine if you can still propagate through the results.	&page=2

### Include depth You can use a total of `2` nested includes on this endpoint ### Include options [`sport`](https://docs.sportmonks.com/v3/core-api/) [`country`](https://docs.sportmonks.com/v3/core-api/) [`stages`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#stage) [`latest`](/v3/endpoints-and-entities/entities/fixture#fixture) [`upcoming`](/v3/endpoints-and-entities/entities/fixture#fixture) [`inplay`](/v3/endpoints-and-entities/entities/fixture#fixture) [`today`](/v3/endpoints-and-entities/entities/fixture#fixture) [`currentSeason`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season) [`seasons`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season) ### **Related Entities:** Get an overview and explanation of all the fields returned in the API response. The related entities for the leagues endpoints are: * [League](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#league) ### Postman We also offer detailed postman documentation with examples and a complete up-to-date version of all our endpoints. Below is a button that lets your fork the collection or import it. \ [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316?action=collection%2Ffork\&collection-url=entityId%3D11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316%26entityType%3Dcollection%26workspaceId%3D17c720d0-d97b-42a9-9ea7-23260ed53ddf) ### Code Example {% tabs %} {% tab title="Ruby" %} ```ruby require "uri" require "net/http" url = URI("https://api.sportmonks.com/v3/football/leagues?api_token=YOUR_TOKEN") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Get.new(url) response = https.request(request) puts response.read_body ``` {% endtab %} {% tab title="Python" %} ```python import http.client conn = http.client.HTTPSConnection("api.sportmonks.com") payload = '' headers = {} conn.request("GET", "/api/v3/football/leagues?api_token=YOUR_TOKEN", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) ``` {% endtab %} {% tab title="PHP" %} ```php 'https://api.sportmonks.com/api/v3/football/leagues?api_token=YOUR_TOKEN', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', )); $response = curl_exec($curl); curl_close($curl); echo $respons ``` {% endtab %} {% tab title="Java" %} ```java OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://api.sportmonks.com/api/v3/football/leagues?api_token=YOUR_TOKEN") .method("GET", null) .build(); Response response = client.newCall(request).execute(); ``` {% endtab %} {% tab title="Node.js" %} ``` var unirest = require('unirest'); var req = unirest('GET', 'https://api.sportmonks.com/api/v3/football/leagues?api_token=YOUR_TOKEN') .end(function (res) { if (res.error) throw new Error(res.error); console.log(res.raw_body); }); ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://api.sportmonks.com/api/v3/football/leagues?api_token=YOUR_TOKEN" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %} # GET League by ID Returns the league you've requested by ID. {% tabs %} {% tab title="Base URL" %} ```javascript https://api.sportmonks.com/v3/football/leagues/{ID} ``` {% endtab %} {% tab title="Example Response" %} ```json { "data": { "id": 501, "sport_id": 1, "country_id": 1161, "name": "Premiership", "active": true, "short_code": "SCO P", "image_path": "https://cdn.sportmonks.com/images/soccer/leagues/501.png", "type": "league", "sub_type": "domestic", "last_played_at": "2024-08-05 19:00:00", "category": 2, "has_jerseys": false }, ``` {% endtab %} {% tab title="Field Description" %}

Field	Description	Type
id	Refers to the unique id of th league	integer
sport_id	Refers to the sport of the league	integer
country_id	Refers to the country of the league	integer
name	The name of the league	string
active	Indicates if the league is active or inactive	integer
short_code	The short code of the league	string / null
image_path	Image path to the league logo	string
type	Indicates the type of the league	string
sub_type	Indicates the subtype of the league	string
last_played_at	The date of when the last fixture was played in the league	string
category	Indicates the category of the league	integer

{% endtab %} {% endtabs %} {% tabs %} {% tab title="Query parameters" %}

Name	Required?	Description
`api_token`	YES Another option is to provide the API token in the header.	Your unique API token. Ex. ?api_token=YOUR_TOKEN
`include`	NO	Enrich the API response with more data by using includes. Ex. &include=participants;events
`select`	NO	Select specific fields on the base entity. Read how to select fields in our tutorial.
`filters`	NO	Filter the API response on multiple related entities. There are static filters and dynamic filters. Please find the possibilities in the Static and Dynamic Filter tab.
`locale`	NO	Translate name fields of the API Response in your selected language. Find more information and which languages are available on our translations page.

Static filters	Available on Entity	Description	Example
N/A	N/A	Not available for this endpoint.	`N/A`

Dynamic filters	Available on Entity	Description	Example
`seasons`	Statistics (players, team, coaches, referees), Standings, and way more. Check this endpoint for all possibilities.	Filter statistics, standings and topscorers based on seasons.	`&include=seasons.statistics&filters=seasonStatisticTypes:TypeIDs` `&include=seasons.statistics&filters=seasonStatisticTypes:52`
`types`	Statistics, Events, Lineup, and way more. Check this endpoint for all possibilities.	Filter the league stages on a selection of type ID's separated by a comma.	`&include=stages.type&filters=stageTypes:TypeIDs` `&include=stages.type&filters=stageTypes:224`

{% endtab %} {% endtabs %} ### Filters More information on how to use filters can be found on our tutorials on how to [filter](https://docs.sportmonks.com/football2/api/request-options/filtering). If you want more information on which filters to use you can check out the following [endpoint](/v3/core-api/endpoints/filters/get-all-entity-filters): {% hint style="info" %} ```javascript https://api.sportmonks.com/v3/my/filters/entity?api_token=YOUR_TOKEN ``` {% endhint %} ### Pagination NO ### Include depth You can use a total of `2` nested includes on this endpoint ### Include options [`sport`](https://docs.sportmonks.com/v3/core-api/) [`country`](https://docs.sportmonks.com/v3/core-api/) [`stages`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#stage) [`latest`](/v3/endpoints-and-entities/entities/fixture#fixture) [`upcoming`](/v3/endpoints-and-entities/entities/fixture#fixture) [`inplay`](/v3/endpoints-and-entities/entities/fixture#fixture) [`today`](/v3/endpoints-and-entities/entities/fixture#fixture) [`currentSeason`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season) [`seasons`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season) ### **Related Entities:** Get an overview and explanation of all the fields returned in the API response. The related entities for the leagues endpoints are: * [League](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#league) ### Postman We also offer detailed postman documentation with examples and a complete up-to-date version of all our endpoints. Below is a button that lets your fork the collection or import it. \ [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316?action=collection%2Ffork\&collection-url=entityId%3D11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316%26entityType%3Dcollection%26workspaceId%3D17c720d0-d97b-42a9-9ea7-23260ed53ddf) ### Code Example {% tabs %} {% tab title="Ruby" %} ```ruby require "uri" require "net/http" url = URI("https://api.sportmonks.com/v3/football/leagues/{ID}?api_token=YOUR_TOKEN") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Get.new(url) response = https.request(request) puts response.read_body ``` {% endtab %} {% tab title="Python" %} ```python import http.client conn = http.client.HTTPSConnection("api.sportmonks.com") payload = '' headers = {} conn.request("GET", "/api/v3/football/leagues/{ID}?api_token=YOUR_TOKEN", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) ``` {% endtab %} {% tab title="PHP" %} ```php 'https://api.sportmonks.com/api/v3/football/leagues/{ID}?api_token=YOUR_TOKEN', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', )); $response = curl_exec($curl); curl_close($curl); echo $respons ``` {% endtab %} {% tab title="Java" %} ```java OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://api.sportmonks.com/api/v3/football/leagues/{ID}?api_token=YOUR_TOKEN") .method("GET", null) .build(); Response response = client.newCall(request).execute(); ``` {% endtab %} {% tab title="Node.js" %} ``` var unirest = require('unirest'); var req = unirest('GET', 'https://api.sportmonks.com/api/v3/football/leagues/{ID}?api_token=YOUR_TOKEN') .end(function (res) { if (res.error) throw new Error(res.error); console.log(res.raw_body); }); ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://api.sportmonks.com/api/v3/football/leagues/{ID}?api_token=YOUR_TOKEN" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %} # GET Leagues by Live Returns all the leagues that have fixtures that are currently being played. {% tabs %} {% tab title="Base URL" %} ```javascript https://api.sportmonks.com/v3/football/leagues/live ``` {% endtab %} {% tab title="Example Response" %} ```json { "data": { "id": 501, "sport_id": 1, "country_id": 1161, "name": "Premiership", "active": true, "short_code": "SCO P", "image_path": "https://cdn.sportmonks.com/images/soccer/leagues/501.png", "type": "league", "sub_type": "domestic", "last_played_at": "2024-08-05 19:00:00", "category": 2, "has_jerseys": false }, ``` {% endtab %} {% tab title="Field Description" %}

Field	Description	Type
id	Refers to the unique id of th league	integer
sport_id	Refers to the sport of the league	integer
country_id	Refers to the country of the league	integer
name	The name of the league	string
active	Indicates if the league is active or inactive	integer
short_code	The short code of the league	string / null
image_path	Image path to the league logo	string
type	Indicates the type of the league	string
sub_type	Indicates the subtype of the league	string
last_played_at	The date of when the last fixture was played in the league	string
category	Indicates the category of the league	integer

{% endtab %} {% endtabs %} {% tabs %} {% tab title="Query parameters" %}

Name	Required?	Description
`api_token`	YES Another option is to provide the API token in the header.	Your unique API token. Ex. ?api_token=YOUR_TOKEN
`include`	NO	Enrich the API response with more data by using includes. Ex. &include=participants;events
`select`	NO	Select specific fields on the base entity. Read how to select fields in our tutorial.
`filters`	NO	Filter the API response on multiple related entities. There are static filters and dynamic filters. Please find the possibilities in the Static and Dynamic Filter tab.
`locale`	NO	Translate name fields of the API Response in your selected language. Find more information and which languages are available on our translations page.

Static filters	Available on Entity	Description	Example
N/A	N/A	Not available for this endpoint.	`N/A`

Dynamic filters	Available on Entity	Description	Example
`countries`	Coaches, Leagues, Players, Teams, and way more. Check this endpoint for all possibilities.	Filter the leagues based on countries.	`&include=country&filters=leagueCountries:countryIDs` `&include=country&filters=leagueCountries:41`
`seasons`	Statistics (players, team, coaches, referees), Standings, and way more. Check this endpoint for all possibilities.	Filter statistics, standings and topscorers based on seasons.	`&include=seasons.statistics&filters=seasonStatisticTypes:TypeIDs` `&include=seasons.statistics&filters=seasonStatisticTypes:52`
`types`	Statistics, Events, Lineup, and way more. Check this endpoint for all possibilities.	Filter the league stages on a selection of type ID's separated by a comma.	`&include=stages.type&filters=stageTypes:TypeIDs` `&include=stages.type&filters=stageTypes:224`

{% endtab %} {% endtabs %} ### Filters More information on how to use filters can be found on our tutorials on how to [filter](https://docs.sportmonks.com/football2/api/request-options/filtering). If you want more information on which filters to use you can check out the following [endpoint](/v3/core-api/endpoints/filters/get-all-entity-filters): {% hint style="info" %} ```javascript https://api.sportmonks.com/v3/my/filters/entity?api_token=YOUR_TOKEN ``` {% endhint %} ### Pagination NO ### Include depth You can use a total of `2` nested includes on this endpoint ### Include options [`sport`](https://docs.sportmonks.com/v3/core-api/) [`country`](https://docs.sportmonks.com/v3/core-api/) [`stages`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#stage) [`latest`](/v3/endpoints-and-entities/entities/fixture#fixture) [`upcoming`](/v3/endpoints-and-entities/entities/fixture#fixture) [`inplay`](/v3/endpoints-and-entities/entities/fixture#fixture) [`today`](/v3/endpoints-and-entities/entities/fixture#fixture) [`currentSeason`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season) [`seasons`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season) ### **Related Entities:** Get an overview and explanation of all the fields returned in the API response. The related entities for the leagues endpoints are: * [League](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#league) ### Postman We also offer detailed postman documentation with examples and a complete up-to-date version of all our endpoints. Below is a button that lets your fork the collection or import it. \ [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316?action=collection%2Ffork\&collection-url=entityId%3D11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316%26entityType%3Dcollection%26workspaceId%3D17c720d0-d97b-42a9-9ea7-23260ed53ddf) ### Code Example {% tabs %} {% tab title="Ruby" %} ```ruby require "uri" require "net/http" url = URI("https://api.sportmonks.com/v3/football/leagues/live?api_token=YOUR_TOKEN") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Get.new(url) response = https.request(request) puts response.read_body ``` {% endtab %} {% tab title="Python" %} ```python import http.client conn = http.client.HTTPSConnection("api.sportmonks.com") payload = '' headers = {} conn.request("GET", "/api/v3/football/leagues/live?api_token=YOUR_TOKEN", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) ``` {% endtab %} {% tab title="PHP" %} ```php 'https://api.sportmonks.com/api/v3/football/leagues/live?api_token=YOUR_TOKEN', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', )); $response = curl_exec($curl); curl_close($curl); echo $respons ``` {% endtab %} {% tab title="Java" %} ```java OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://api.sportmonks.com/api/v3/football/leagues/live?api_token=YOUR_TOKEN") .method("GET", null) .build(); Response response = client.newCall(request).execute(); ``` {% endtab %} {% tab title="Node.js" %} ``` var unirest = require('unirest'); var req = unirest('GET', 'https://api.sportmonks.com/api/v3/football/leagues/live?api_token=YOUR_TOKEN') .end(function (res) { if (res.error) throw new Error(res.error); console.log(res.raw_body); }); ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://api.sportmonks.com/api/v3/football/leagues/live?api_token=YOUR_TOKEN" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %} # GET Leagues by Fixture Date Returns all the leagues with fixtures from your requested fixture date. {% tabs %} {% tab title="Base URL" %} ```javascript https://api.sportmonks.com/v3/football/leagues/date/{date} ``` {% endtab %} {% tab title="Example Response" %} ```json { "data": [ { "id": 271, "sport_id": 1, "country_id": 320, "name": "Superliga", "active": true, "short_code": "DNK SL", "image_path": "https://cdn.sportmonks.com/images/soccer/leagues/271.png", "type": "league", "sub_type": "domestic", "last_played_at": "2024-08-05 17:00:00", "category": 2, "has_jerseys": false }, { "id": 501, "sport_id": 1, "country_id": 1161, "name": "Premiership", "active": true, "short_code": "SCO P", "image_path": "https://cdn.sportmonks.com/images/soccer/leagues/501.png", "type": "league", "sub_type": "domestic", "last_played_at": "2024-08-05 19:00:00", "category": 2, "has_jerseys": false } ``` {% endtab %} {% tab title="Field Description" %}

Field	Description	Type
id	Refers to the unique id of th league	integer
sport_id	Refers to the sport of the league	integer
country_id	Refers to the country of the league	integer
name	The name of the league	string
active	Indicates if the league is active or inactive	integer
short_code	The short code of the league	string / null
image_path	Image path to the league logo	string
type	Indicates the type of the league	string
sub_type	Indicates the subtype of the league	string
last_played_at	The date of when the last fixture was played in the league	string
category	Indicates the category of the league	integer

{% endtab %} {% endtabs %} {% tabs %} {% tab title="Query parameters" %}

Name	Required?	Description
`api_token`	YES Another option is to provide the API token in the header.	Your unique API token. Ex. ?api_token=YOUR_TOKEN
`include`	NO	Enrich the API response with more data by using includes. Ex. &include=participants;events
`select`	NO	Select specific fields on the base entity. Read how to select fields in our tutorial.
`filters`	NO	Filter the API response on multiple related entities. There are static filters and dynamic filters. Please find the possibilities in the Static and Dynamic Filter tab.
`locale`	NO	Translate name fields of the API Response in your selected language. Find more information and which languages are available on our translations page.

Static filters	Available on Entity	Description	Example
N/A	N/A	Not available for this endpoint.	N/A

Dynamic filters	Available on Entity	Description	Example
`countries`	Coaches, Leagues, Players, Teams, and way more. Check this endpoint for all possibilities.	Filter the leagues based on countries.	`&include=country&filters=leagueCountries:countryIDs` `&include=country&filters=leagueCountries:41`
`seasons`	Statistics (players, team, coaches, referees), Standings, and way more. Check this endpoint for all possibilities.	Filter statistics, standings and topscorers based on seasons.	`&include=seasons.statistics&filters=seasonStatisticTypes:TypeIDs` `&include=seasons.statistics&filters=seasonStatisticTypes:52`
`types`	Statistics, Events, Lineup, and way more. Check this endpoint for all possibilities.	Filter the league stages on a selection of type ID's separated by a comma.	`&include=stages.type&filters=stageTypes:TypeIDs` `&include=stages.type&filters=stageTypes:224`

Parameter	Required	Description	Example
`order`	No	Returns leagues ordered by id (`asc` or `desc`). Defaults to asc (if league priority is not present).	&order=desc
`per_page`	No	The amount of results to return per page (max 50.). Defaults to 25.	&per_page=30
`page`	No	You can paginate using the `has_more` parameter to determine if you can still propagate through the results.	&page=2

### Include depth You can use a total of `2` nested includes on this endpoint ### Include options [`sport`](https://docs.sportmonks.com/v3/core-api/) [`country`](https://docs.sportmonks.com/v3/core-api/) [`stages`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#stage) [`latest`](/v3/endpoints-and-entities/entities/fixture#fixture) [`upcoming`](/v3/endpoints-and-entities/entities/fixture#fixture) [`inplay`](/v3/endpoints-and-entities/entities/fixture#fixture) [`today`](/v3/endpoints-and-entities/entities/fixture#fixture) [`currentSeason`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season) [`seasons`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season) ### **Related Entities:** Get an overview and explanation of all the fields returned in the API response. The related entities for the leagues endpoints are: * [League](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#league) ### Postman We also offer detailed postman documentation with examples and a complete up-to-date version of all our endpoints. Below is a button that lets your fork the collection or import it. \ [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316?action=collection%2Ffork\&collection-url=entityId%3D11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316%26entityType%3Dcollection%26workspaceId%3D17c720d0-d97b-42a9-9ea7-23260ed53ddf) ### Code Example {% tabs %} {% tab title="Ruby" %} ```ruby require "uri" require "net/http" url = URI("https://api.sportmonks.com/v3/football/leagues/fixtures/date/{date}?api_token=YOUR_TOKEN") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Get.new(url) response = https.request(request) puts response.read_body ``` {% endtab %} {% tab title="Python" %} ```python import http.client conn = http.client.HTTPSConnection("api.sportmonks.com") payload = '' headers = {} conn.request("GET", "/api/v3/football/leagues/fixtures/date/{date}?api_token=YOUR_TOKEN", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) ``` {% endtab %} {% tab title="PHP" %} ```php 'https://api.sportmonks.com/api/v3/football/leagues/fixtures/date/{date}?api_token=YOUR_TOKEN', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', )); $response = curl_exec($curl); curl_close($curl); echo $respons ``` {% endtab %} {% tab title="Java" %} ```java OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://api.sportmonks.com/api/v3/football/leagues/fixtures/date/{date}?api_token=YOUR_TOKEN") .method("GET", null) .build(); Response response = client.newCall(request).execute(); ``` {% endtab %} {% tab title="Node.js" %} ``` var unirest = require('unirest'); var req = unirest('GET', 'https://api.sportmonks.com/api/v3/football/leagues/fixtures/date/{date}?api_token=YOUR_TOKEN') .end(function (res) { if (res.error) throw new Error(res.error); console.log(res.raw_body); }); ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://api.sportmonks.com/api/v3/football/leagues/fixtures/date/{date}?api_token=YOUR_TOKEN" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %} # GET Leagues by Country ID Returns all the leagues from your requested country ID. {% tabs %} {% tab title="Base URL" %} ```javascript https://api.sportmonks.com/v3/football/leagues/countries/{ID} ``` {% endtab %} {% tab title="Example Response" %} ```json { "data": [ { "id": 501, "sport_id": 1, "country_id": 1161, "name": "Premiership", "active": true, "short_code": "SCO P", "image_path": "https://cdn.sportmonks.com/images/soccer/leagues/501.png", "type": "league", "sub_type": "domestic", "last_played_at": "2024-08-05 19:00:00", "category": 2, "has_jerseys": false }, { "id": 513, "sport_id": 1, "country_id": 1161, "name": "Premiership Play-Offs", "active": true, "short_code": "SCO P PO", "image_path": "https://cdn.sportmonks.com/images/soccer/leagues/1/513.png", "type": "league", "sub_type": "play-offs", "last_played_at": "2024-05-26 11:00:00", "category": 2, "has_jerseys": false } ``` {% endtab %} {% tab title="Field Description" %}

Field	Description	Type
id	Refers to the unique id of th league	integer
sport_id	Refers to the sport of the league	integer
country_id	Refers to the country of the league	integer
name	The name of the league	string
active	Indicates if the league is active or inactive	integer
short_code	The short code of the league	string / null
image_path	Image path to the league logo	string
type	Indicates the type of the league	string
sub_type	Indicates the subtype of the league	string
last_played_at	The date of when the last fixture was played in the league	string
category	Indicates the category of the league	integer

{% endtab %} {% endtabs %} {% tabs %} {% tab title="Query parameters" %}

Name	Required?	Description
`api_token`	YES Another option is to provide the API token in the header.	Your unique API token. Ex. ?api_token=YOUR_TOKEN
`include`	NO	Enrich the API response with more data by using includes. Ex. &include=participants;events
`select`	NO	Select specific fields on the base entity. Read how to select fields in our tutorial.
`filters`	NO	Filter the API response on multiple related entities. There are static filters and dynamic filters. Please find the possibilities in the Static and Dynamic Filter tab.
`locale`	NO	Translate name fields of the API Response in your selected language. Find more information and which languages are available on our translations page.

Static filters	Available on Entity	Description	Example
N/A	N/A	Not available for this endpoint.	`N/A`

Dynamic filters	Available on Entity	Description	Example
`seasons`	Statistics (players, team, coaches, referees), Standings, and way more. Check this endpoint for all possibilities.	Filter statistics, standings and topscorers based on seasons.	`&include=seasons.statistics&filters=seasonStatisticTypes:TypeIDs` `&include=seasons.statistics&filters=seasonStatisticTypes:52`
`types`	Statistics, Events, Lineup, and way more. Check this endpoint for all possibilities.	Filter the league stages on a selection of type ID's separated by a comma.	`&include=stages.type&filters=stageTypes:TypeIDs` `&include=stages.type&filters=stageTypes:224`

{% endtab %} {% endtabs %} ### Filters More information on how to use filters can be found on our tutorials on how to [filter](https://docs.sportmonks.com/football2/api/request-options/filtering). If you want more information on which filters to use you can check out the following [endpoint](/v3/core-api/endpoints/filters/get-all-entity-filters): {% hint style="info" %} ```javascript https://api.sportmonks.com/v3/my/filters/entity?api_token=YOUR_TOKEN ``` {% endhint %} ### Pagination YES ### Include depth You can use a total of `2` nested includes on this endpoint ### Include options [`sport`](https://docs.sportmonks.com/v3/core-api/) [`country`](https://docs.sportmonks.com/v3/core-api/) [`stages`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#stage) [`latest`](/v3/endpoints-and-entities/entities/fixture#fixture) [`upcoming`](/v3/endpoints-and-entities/entities/fixture#fixture) [`inplay`](/v3/endpoints-and-entities/entities/fixture#fixture) [`today`](/v3/endpoints-and-entities/entities/fixture#fixture) [`currentSeason`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season) [`seasons`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season) ### **Related Entities:** Get an overview and explanation of all the fields returned in the API response. The related entities for the leagues endpoints are: * [League](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#league) ### Postman We also offer detailed postman documentation with examples and a complete up-to-date version of all our endpoints. Below is a button that lets your fork the collection or import it. \ [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316?action=collection%2Ffork\&collection-url=entityId%3D11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316%26entityType%3Dcollection%26workspaceId%3D17c720d0-d97b-42a9-9ea7-23260ed53ddf) ### Code Example {% tabs %} {% tab title="Ruby" %} ```ruby require "uri" require "net/http" url = URI("https://api.sportmonks.com/v3/football/leagues/countries/{ID}?api_token=YOUR_TOKEN") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Get.new(url) response = https.request(request) puts response.read_body ``` {% endtab %} {% tab title="Python" %} ```python import http.client conn = http.client.HTTPSConnection("api.sportmonks.com") payload = '' headers = {} conn.request("GET", "/api/v3/football/leagues/countries/{ID}?api_token=YOUR_TOKEN", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) ``` {% endtab %} {% tab title="PHP" %} ```php 'https://api.sportmonks.com/api/v3/football/leagues/countries/{ID}?api_token=YOUR_TOKEN', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', )); $response = curl_exec($curl); curl_close($curl); echo $respons ``` {% endtab %} {% tab title="Java" %} ```java OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://api.sportmonks.com/api/v3/football/leagues/countries/{ID}?api_token=YOUR_TOKEN") .method("GET", null) .build(); Response response = client.newCall(request).execute(); ``` {% endtab %} {% tab title="Node.js" %} ``` var unirest = require('unirest'); var req = unirest('GET', 'https://api.sportmonks.com/api/v3/football/leagues/countries/{ID}?api_token=YOUR_TOKEN') .end(function (res) { if (res.error) throw new Error(res.error); console.log(res.raw_body); }); ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://api.sportmonks.com/api/v3/football/leagues/countries/{ID}?api_token=YOUR_TOKEN" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %} # GET Leagues Search by Name Returns all the leagues that match your search query. {% tabs %} {% tab title="Base URL" %} ```javascript https://api.sportmonks.com/v3/football/leagues/search/{search_query} ``` {% endtab %} {% tab title="Example Response" %} ```json { "data": [ { "id": 501, "sport_id": 1, "country_id": 1161, "name": "Premiership", "active": true, "short_code": "SCO P", "image_path": "https://cdn.sportmonks.com/images/soccer/leagues/501.png", "type": "league", "sub_type": "domestic", "last_played_at": "2024-08-05 19:00:00", "category": 2, "has_jerseys": false }, { "id": 513, "sport_id": 1, "country_id": 1161, "name": "Premiership Play-Offs", "active": true, "short_code": "SCO P PO", "image_path": "https://cdn.sportmonks.com/images/soccer/leagues/1/513.png", "type": "league", "sub_type": "play-offs", "last_played_at": "2024-05-26 11:00:00", "category": 2, "has_jerseys": false } ``` {% endtab %} {% tab title="Field Description" %}

Field	Description	Type
id	Refers to the unique id of th league	integer
sport_id	Refers to the sport of the league	integer
country_id	Refers to the country of the league	integer
name	The name of the league	string
active	Indicates if the league is active or inactive	integer
short_code	The short code of the league	string / null
image_path	Image path to the league logo	string
type	Indicates the type of the league	string
sub_type	Indicates the subtype of the league	string
last_played_at	The date of when the last fixture was played in the league	string
category	Indicates the category of the league	integer

{% endtab %} {% endtabs %} {% tabs %} {% tab title="Query parameters" %}

Name	Required?	Description
`api_token`	YES Another option is to provide the API token in the header.	Your unique API token. Ex. ?api_token=YOUR_TOKEN
`include`	NO	Enrich the API response with more data by using includes. Ex. &include=participants;events
`select`	NO	Select specific fields on the base entity. Read how to select fields in our tutorial.
`filters`	NO	Filter the API response on multiple related entities. There are static filters and dynamic filters. Please find the possibilities in the Static and Dynamic Filter tab.
`locale`	NO	Translate name fields of the API Response in your selected language. Find more information and which languages are available on our translations page.

Static filters	Available on Entity	Description	Example
N/A	N/A	Not available for this endpoint.	`N/A`

Dynamic filters	Available on Entity	Description	Example
`countries`	Coaches, Leagues, Players, Teams, and way more. Check this endpoint for all possibilities.	Filter the leagues based on countries.	`&include=country&filters=leagueCountries:countryIDs` `&include=country&filters=leagueCountries:41`
`seasons`	Statistics (players, team, coaches, referees), Standings, and way more. Check this endpoint for all possibilities.	Filter statistics, standings and topscorers based on seasons.	`&include=seasons.statistics&filters=seasonStatisticTypes:TypeIDs` `&include=seasons.statistics&filters=seasonStatisticTypes:52`
`types`	Statistics, Events, Lineup, and way more. Check this endpoint for all possibilities.	Filter the league stages on a selection of type ID's separated by a comma.	`&include=stages.type&filters=stageTypes:TypeIDs` `&include=stages.type&filters=stageTypes:224`

Parameter	Required	Description	Example
`order`	No	Returns leagues ordered by category (`asc` or `desc`). Defaults to asc	&order=desc
`per_page`	No	The amount of results to return per page (max 50.). Defaults to 25.	&per_page=30
`page`	No	You can paginate using the `has_more` parameter to determine if you can still propagate through the results.	&page=2

### Include depth You can use a total of `2` nested includes on this endpoint ### Include options [`sport`](https://docs.sportmonks.com/v3/core-api/) [`country`](https://docs.sportmonks.com/v3/core-api/) [`stages`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#stage) [`latest`](/v3/endpoints-and-entities/entities/fixture#fixture) [`upcoming`](/v3/endpoints-and-entities/entities/fixture#fixture) [`inplay`](/v3/endpoints-and-entities/entities/fixture#fixture) [`today`](/v3/endpoints-and-entities/entities/fixture#fixture) [`currentSeason`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season) [`seasons`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season) ### **Related Entities:** Get an overview and explanation of all the fields returned in the API response. The related entities for the leagues endpoints are: * [League](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#league) ### Postman We also offer detailed postman documentation with examples and a complete up-to-date version of all our endpoints. Below is a button that lets your fork the collection or import it. \ [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316?action=collection%2Ffork\&collection-url=entityId%3D11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316%26entityType%3Dcollection%26workspaceId%3D17c720d0-d97b-42a9-9ea7-23260ed53ddf) ### Code Example {% tabs %} {% tab title="Ruby" %} ```ruby require "uri" require "net/http" url = URI("https://api.sportmonks.com/v3/football/leagues/search/{search_query}?api_token=YOUR_TOKEN") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Get.new(url) response = https.request(request) puts response.read_body ``` {% endtab %} {% tab title="Python" %} ```python import http.client conn = http.client.HTTPSConnection("api.sportmonks.com") payload = '' headers = {} conn.request("GET", "/api/v3/football/leagues/search/{search_query}?api_token=YOUR_TOKEN", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) ``` {% endtab %} {% tab title="PHP" %} ```php 'https://api.sportmonks.com/api/v3/football/leagues/search/{search_query}?api_token=YOUR_TOKEN', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', )); $response = curl_exec($curl); curl_close($curl); echo $respons ``` {% endtab %} {% tab title="Java" %} ```java OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://api.sportmonks.com/api/v3/football/leagues/search/{search_query}?api_token=YOUR_TOKEN") .method("GET", null) .build(); Response response = client.newCall(request).execute(); ``` {% endtab %} {% tab title="Node.js" %} ``` var unirest = require('unirest'); var req = unirest('GET', 'https://api.sportmonks.com/api/v3/football/leagues/search/{search_query}?api_token=YOUR_TOKEN') .end(function (res) { if (res.error) throw new Error(res.error); console.log(res.raw_body); }); ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://api.sportmonks.com/api/v3/football/leagues/search/{search_query}?api_token=YOUR_TOKEN" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %} # GET All Leagues by Team ID Returns all the current and historical leagues from your requested team id. {% tabs %} {% tab title="Base URL" %} ```javascript https://api.sportmonks.com/v3/football/leagues/teams/{ID} ``` {% endtab %} {% tab title="Example Response" %} ```json {{ "data": [ { "id": 501, "sport_id": 1, "country_id": 1161, "name": "Premiership", "active": true, "short_code": "SCO P", "image_path": "https://cdn.sportmonks.com/images/soccer/leagues/501.png", "type": "league", "sub_type": "domestic", "last_played_at": "2024-08-05 19:00:00", "category": 2, "has_jerseys": false }, { "id": 513, "sport_id": 1, "country_id": 1161, "name": "Premiership Play-Offs", "active": true, "short_code": "SCO P PO", "image_path": "https://cdn.sportmonks.com/images/soccer/leagues/1/513.png", "type": "league", "sub_type": "play-offs", "last_played_at": "2024-05-26 11:00:00", "category": 2, "has_jerseys": false } ``` {% endtab %} {% tab title="Field Description" %}

Field	Description	Type
id	Refers to the unique id of th league	integer
sport_id	Refers to the sport of the league	integer
country_id	Refers to the country of the league	integer
name	The name of the league	string
active	Indicates if the league is active or inactive	integer
short_code	The short code of the league	string / null
image_path	Image path to the league logo	string
type	Indicates the type of the league	string
sub_type	Indicates the subtype of the league	string
last_played_at	The date of when the last fixture was played in the league	string
category	Indicates the category of the league	integer

{% endtab %} {% endtabs %} {% tabs %} {% tab title="Query parameters" %}

Name	Required?	Description
`api_token`	YES Another option is to provide the API token in the header.	Your unique API token. Ex. ?api_token=YOUR_TOKEN
`include`	NO	Enrich the API response with more data by using includes. Ex. &include=participants;events
`select`	NO	Select specific fields on the base entity. Read how to select fields in our tutorial.
`filters`	NO	Filter the API response on multiple related entities. There are static filters and dynamic filters. Please find the possibilities in the Static and Dynamic Filter tab.
`locale`	NO	Translate name fields of the API Response in your selected language. Find more information and which languages are available on our translations page.

Static filters	Available on Entity	Description	Example
N/A	N/A	Not available for this endpoint.	`N/A`

Dynamic filters	Available on Entity	Description	Example
`countries`	Coaches, Leagues, Players, Teams, and way more. Check this endpoint for all possibilities.	Filter the leagues based on countries.	`&include=country&filters=leagueCountries:countryIDs` `&include=country&filters=leagueCountries:41`
`seasons`	Statistics (players, team, coaches, referees), Standings, and way more. Check this endpoint for all possibilities.	Filter statistics, standings and topscorers based on seasons.	`&include=seasons.statistics&filters=seasonStatisticTypes:TypeIDs` `&include=seasons.statistics&filters=seasonStatisticTypes:52`
`types`	Statistics, Events, Lineup, and way more. Check this endpoint for all possibilities.	Filter the league stages on a selection of type ID's separated by a comma.	`&include=stages.type&filters=stageTypes:TypeIDs` `&include=stages.type&filters=stageTypes:224`

Parameter	Required	Description	Example
`order`	No	Returns leagues ordered by id (`asc` or `desc`). Defaults to asc	&order=desc
`per_page`	No	The amount of results to return per page (max 50.). Defaults to 25.	&per_page=30
`page`	No	You can paginate using the `has_more` parameter to determine if you can still propagate through the results.	&page=2

### Include depth You can use a total of `2` nested includes on this endpoint ### Include options [`sport`](https://docs.sportmonks.com/v3/core-api/) [`country`](https://docs.sportmonks.com/v3/core-api/) [`stages`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#stage) [`latest`](/v3/endpoints-and-entities/entities/fixture#fixture) [`upcoming`](/v3/endpoints-and-entities/entities/fixture#fixture) [`inplay`](/v3/endpoints-and-entities/entities/fixture#fixture) [`today`](/v3/endpoints-and-entities/entities/fixture#fixture) [`currentSeason`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season) [`seasons`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season) ### **Related Entities** Get an overview and explanation of all the fields returned in the API response. The related entities for the leagues endpoints are: * [League](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#league) ### Postman We also offer detailed postman documentation with examples and a complete up-to-date version of all our endpoints. Below is a button that lets your fork the collection or import it. \ [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316?action=collection%2Ffork\&collection-url=entityId%3D11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316%26entityType%3Dcollection%26workspaceId%3D17c720d0-d97b-42a9-9ea7-23260ed53ddf) ### Code Example {% tabs %} {% tab title="Ruby" %} ```ruby require "uri" require "net/http" url = URI("https://api.sportmonks.com/v3/football/leagues/teams/{ID}?api_token=YOUR_TOKEN") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Get.new(url) response = https.request(request) puts response.read_body ``` {% endtab %} {% tab title="Python" %} ```python import http.client conn = http.client.HTTPSConnection("api.sportmonks.com") payload = '' headers = {} conn.request("GET", "/api/v3/football/leagues/teams/{ID}?api_token=YOUR_TOKEN", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) ``` {% endtab %} {% tab title="PHP" %} ```php 'https://api.sportmonks.com/api/v3/football/leagues/teams/{ID}?api_token=YOUR_TOKEN', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', )); $response = curl_exec($curl); curl_close($curl); echo $respons ``` {% endtab %} {% tab title="Java" %} ```java OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://api.sportmonks.com/api/v3/football/leagues/teams/{ID}?api_token=YOUR_TOKEN") .method("GET", null) .build(); Response response = client.newCall(request).execute(); ``` {% endtab %} {% tab title="Node.js" %} ``` var unirest = require('unirest'); var req = unirest('GET', 'https://api.sportmonks.com/api/v3/football/leagues/teams/{ID}?api_token=YOUR_TOKEN') .end(function (res) { if (res.error) throw new Error(res.error); console.log(res.raw_body); }); ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://api.sportmonks.com/api/v3/football/leagues/teams/{ID}?api_token=YOUR_TOKEN" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %} # GET Current Leagues by Team ID Returns all the current leagues of your requested team id. {% tabs %} {% tab title="Base URL" %} ```javascript https://api.sportmonks.com/v3/football/leagues/teams/{ID}/current ``` {% endtab %} {% tab title="Example Response" %} ```json { "data": [ { "id": 501, "sport_id": 1, "country_id": 1161, "name": "Premiership", "active": true, "short_code": "SCO P", "image_path": "https://cdn.sportmonks.com/images/soccer/leagues/501.png", "type": "league", "sub_type": "domestic", "last_played_at": "2024-08-05 19:00:00", "category": 2, "has_jerseys": false } ``` {% endtab %} {% tab title="Field Description" %}

Field	Description	Type
id	Refers to the unique id of th league	integer
sport_id	Refers to the sport of the league	integer
country_id	Refers to the country of the league	integer
name	The name of the league	string
active	Indicates if the league is active or inactive	integer
short_code	The short code of the league	string / null
image_path	Image path to the league logo	string
type	Indicates the type of the league	string
sub_type	Indicates the subtype of the league	string
last_played_at	The date of when the last fixture was played in the league	string
category	Indicates the category of the league	integer

{% endtab %} {% endtabs %} {% tabs %} {% tab title="Query parameters" %}

Name	Required?	Description
`api_token`	YES Another option is to provide the API token in the header.	Your unique API token. Ex. ?api_token=YOUR_TOKEN
`include`	NO	Enrich the API response with more data by using includes. Ex. &include=participants;events
`select`	NO	Select specific fields on the base entity. Read how to select fields in our tutorial.
`filters`	NO	Filter the API response on multiple related entities. There are static filters and dynamic filters. Please find the possibilities in the Static and Dynamic Filter tab.
`locale`	NO	Translate name fields of the API Response in your selected language. Find more information and which languages are available on our translations page.

Static filters	Available on Entity	Description	Example
N/A	N/A	Not available for this endpoint.	`N/A`

Dynamic filters	Available on Entity	Description	Example
`countries`	Coaches, Leagues, Players, Teams, and way more. Check this endpoint for all possibilities.	Filter the leagues based on countries.	`&include=country&filters=leagueCountries:countryIDs` `&include=country&filters=leagueCountries:41`
`seasons`	Statistics (players, team, coaches, referees), Standings, and way more. Check this endpoint for all possibilities.	Filter statistics, standings and topscorers based on seasons.	`&include=seasons.statistics&filters=seasonStatisticTypes:TypeIDs` `&include=seasons.statistics&filters=seasonStatisticTypes:52`
`types`	Statistics, Events, Lineup, and way more. Check this endpoint for all possibilities.	Filter the league stages on a selection of type ID's separated by a comma.	`&include=stages.type&filters=stageTypes:TypeIDs` `&include=stages.type&filters=stageTypes:224`

{% endtab %} {% endtabs %} ### Filters More information on how to use filters can be found on our tutorials on how to [filter](https://docs.sportmonks.com/football2/api/request-options/filtering). If you want more information on which filters to use you can check out the following [endpoint](/v3/core-api/endpoints/filters/get-all-entity-filters): {% hint style="info" %} ```javascript https://api.sportmonks.com/v3/my/filters/entity?api_token=YOUR_TOKEN ``` {% endhint %} ### Pagination YES ### Include depth You can use a total of `2` nested includes on this endpoint ### Include options [`sport`](https://docs.sportmonks.com/v3/core-api/) [`country`](https://docs.sportmonks.com/v3/core-api/) [`stages`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#stage) [`latest`](/v3/endpoints-and-entities/entities/fixture#fixture) [`upcoming`](/v3/endpoints-and-entities/entities/fixture#fixture) [`inplay`](/v3/endpoints-and-entities/entities/fixture#fixture) [`today`](/v3/endpoints-and-entities/entities/fixture#fixture) [`currentSeason`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season) [`seasons`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season) ### **Related Entities:** Get an overview and explanation of all the fields returned in the API response. The related entities for the leagues endpoints are: * [League](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#league) ### Code Example {% tabs %} {% tab title="Ruby" %} ```ruby require "uri" require "net/http" url = URI("https://api.sportmonks.com/v3/football/leagues/teams/{ID}/current?api_token=YOUR_TOKEN") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Get.new(url) response = https.request(request) puts response.read_body ``` {% endtab %} {% tab title="Python" %} ```python import http.client conn = http.client.HTTPSConnection("api.sportmonks.com") payload = '' headers = {} conn.request("GET", "/api/v3/football/leagues/teams/{ID}/current?api_token=YOUR_TOKEN", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) ``` {% endtab %} {% tab title="PHP" %} ```php 'https://api.sportmonks.com/api/v3/football/leagues/teams/{ID}/current?api_token=YOUR_TOKEN', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', )); $response = curl_exec($curl); curl_close($curl); echo $respons ``` {% endtab %} {% tab title="Java" %} ```java OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://api.sportmonks.com/api/v3/football/leagues/teams/{ID}/current?api_token=YOUR_TOKEN") .method("GET", null) .build(); Response response = client.newCall(request).execute(); ``` {% endtab %} {% tab title="Node.js" %} ``` var unirest = require('unirest'); var req = unirest('GET', 'https://api.sportmonks.com/api/v3/football/leagues/teams/{ID}/current?api_token=YOUR_TOKEN') .end(function (res) { if (res.error) throw new Error(res.error); console.log(res.raw_body); }); ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://api.sportmonks.com/api/v3/football/leagues/teams/{ID}/current?api_token=YOUR_TOKEN" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %} # Seasons Gather an overview of all the historical and current seasons available within your subscription. Responses provide you details like the Season ID, Name, League ID, Year and if the Season is Active Yes or No. {% hint style="info" %} Are you interested in a complete schedule? Then maybe our schedule endpoints are what you’re looking for: [Schedule endpoint](/v3/endpoints-and-entities/endpoints/schedules). {% endhint %} Use one of our 3 season endpoints. Per endpoint, you can find the details, including base URL, parameters, includes and more. * **GET All Seasons:** returns all the historical and active seasons that are available within your subscription. * **GET Season by ID:** returns the single-season you’ve requested by ID. * **GET Seasons by Search by Name:** returns all seasons that match your search query.

### Include options [`sport`](https://docs.sportmonks.com/v3/core-api/) [`league`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#league) [`teams`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#team) [`stages`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#stage) [`currentStage`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#stage) [`fixtures`](/v3/endpoints-and-entities/entities/fixture#fixture) [`groups`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#group) [`statistics`](/v3/endpoints-and-entities/entities/statistic#seasonstatistic) [`topscorers`](/v3/endpoints-and-entities/entities/standing-and-topscorer#topscorers) ### **Related Entities:** Get an overview and explanation of all the fields returned in the API response. The related entities for the seasons endpoints are: * [Season](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season) {% hint style="info" %} Remember, our historical data will be integrated into the new version of our API gradually. So, the historical data is not yet complete. However, we will be loading more historical data continuously. {% endhint %} # GET All Seasons Returns all the seasons available within your subscription. {% tabs %} {% tab title="Base URL" %} ```javascript https://api.sportmonks.com/v3/football/seasons ``` {% endtab %} {% tab title="Example Response" %} ```json { "data": [ { "id": 21644, "sport_id": 1, "league_id": 271, "tie_breaker_rule_id": 171, "name": "2023/2024", "finished": true, "pending": false, "is_current": false, "starting_at": "2023-07-21", "ending_at": "2024-05-31", "standings_recalculated_at": "2024-05-26 17:02:52", "games_in_current_week": false }, { "id": 21787, "sport_id": 1, "league_id": 501, "tie_breaker_rule_id": 171, "name": "2023/2024", "finished": true, "pending": false, "is_current": false, "starting_at": "2023-08-05", "ending_at": "2024-05-19", "standings_recalculated_at": "2024-05-19 16:00:59", "games_in_current_week": false }, ``` {% endtab %} {% tab title="Field Description" %}

Field	Description	Type
id	Refers to the id of the season	integer
sport_id	Refers to the sport of the season	integer
league_id	Refers to the league of the season	integer
tie_breaker_rule_id	Refers to the type of tie-breaker rule used to determine the season winner	integer
name	The name of the season	string
finished	Indicates if the season finished or not	integer
pending	Indicates if the season is pending or not	integer
is_current	Indicates if the season is the current season or not	integer
standing_method	Returns the standing calculation used in the season	string
starting_at	The starting date of the season	string
ending_at	The end date of the season	string

{% endtab %} {% endtabs %} {% tabs %} {% tab title="Query Parameters" %}

Name	Required?	Description
`api_token`	YES Another option is to provide the API token in the header.	Your unique API token. Ex. ?api_token=YOUR_TOKEN
`include`	NO	Enrich the API response with more data by using includes. Ex. &include=participants;events
`select`	NO	Select specific fields on the base entity. Read how to select fields in our tutorial.
`filters`	NO	Filter the API response on multiple related entities. There are static filters and dynamic filters. Please find the possibilities in the Static and Dynamic Filter tab.
`locale`	NO	Translate name fields of the API Response in your selected language. Find more information and which languages are available on our translations page.

Static filters	Available on Entity	Description	Example
`IdAfter`	All	Filter all seasons starting from a certain season ID.	`&filters=IdAfter:seasonId` `&filters=IdAfter:18017`

{% endtab %} {% tab title="Dynamic Filters" %} The **dynamic filters** are based on entities and includes. Each dynamic filter uses an entity to filter on and one entity to apply the filter on. Below are examples with explanations of how filters are set up. For more information, please look at our[ Filters page](/v3/api/request-options/filtering). {% hint style="info" %} Using an include? Check their respective filters on their entity page. For example, if you use `&include=fixtures`, you can apply [fixture-related filters](/v3/endpoints-and-entities/entities/fixture#fixture-entity-filters). {% endhint %}

Dynamic Filters	Available on Entity	Description	Examples
`types`	Statistics, Events, Lineup, and way more. Check this endpoint for all possibilities.	Filter the season statistics on a selection of types separated by a comma.	`&include=statistics&filters=seasonstatisticTypes:TypeIDs` `&include=statistics&filters=seasonstatisticTypes:52,88`
`leagues`	Fixtures, Seasons, Standings, and way more. Check this endpoint for all possibilities.	Filter the seasons based on leagues.	`&include=league&&filters=seasonLeagues:leagueIDs` `&include=league&&filters=seasonLeagues:2,8`
`stages`	Check this endpoint for all possibilities.	Filter season stages based on stage IDs	`&filters=stageStages:stageIDS` `&filters=stageStages:77457866`
`rounds`	Check this endpoint for all possibilities.	Filter season rounds based on round IDs	`&filters=roundRounds:roundIDS` `&filters=roundRounds:290018`
`topscorers`	Check this endpoint for all possibilities.	Filter season topscorers based on type IDs	`&include=topscorers&filters=seasonTopscorerTypes:TypeIDs` `&include=topscorers&filters=seasonTopscorerTypes:208`

Parameter	Required	Description	Example
`order`	No	Returns seasons ordered by id (`asc` or `desc`). Defaults to asc	&order=desc
`per_page`	No	The amount of results to return per page (max 50.). Defaults to 25.	&per_page=30
`page`	No	You can paginate using the `has_more` parameter to determine if you can still propagate through the results.	&page=2

Field	Description	Type
id	Refers to the id of the season	integer
sport_id	Refers to the sport of the season	integer
league_id	Refers to the league of the season	integer
tie_breaker_rule_id	Refers to the type of tie-breaker rule used to determine the season winner	integer
name	The name of the season	string
finished	Indicates if the season finished or not	integer
pending	Indicates if the season is pending or not	integer
is_current	Indicates if the season is the current season or not	integer
standing_method	Returns the standing calculation used in the season	string
starting_at	The starting date of the season	string
ending_at	The end date of the season	string

{% endtab %} {% endtabs %} {% tabs %} {% tab title="Query Parameters" %}

Name	Required?	Description
`api_token`	YES Another option is to provide the API token in the header.	Your unique API token. Ex. ?api_token=YOUR_TOKEN
`include`	NO	Enrich the API response with more data by using includes. Ex. &include=participants;events
`select`	NO	Select specific fields on the base entity. Read how to select fields in our tutorial.
`filters`	NO	Filter the API response on multiple related entities. There are static filters and dynamic filters. Please find the possibilities in the Static and Dynamic Filter tab.
`locale`	NO	Translate name fields of the API Response in your selected language. Find more information and which languages are available on our translations page.

Static filters	Available on Entity	Description	Example
N/A	N/A	Not available for this endpoint.	`N/A`

{% endtab %} {% tab title="Dynamic Filters" %} The **dynamic filters** are based on entities and includes. Each dynamic filter uses an entity to filter on and one entity to apply the filter on. Below are examples with explanations of how filters are set up. For more information, please look at our[ Filters page](/v3/api/request-options/filtering). {% hint style="info" %} Using an include? Check their respective filters on their entity page. For example if you use `&include=fixtures`, you can apply [fixture-related filters](/v3/endpoints-and-entities/entities/fixture#fixture-entity-filters). {% endhint %}

Dynamic Filters	Available on Entity	Description	Examples
`types`	Statistics, Events, Lineup, and way more. Check this endpoint for all possibilities.	Filter the season statistics on a selection of types separated by a comma.	`&include=statistics&filters=seasonstatisticTypes:TypeIDs` `&include=statistics&filters=seasonstatisticTypes:52,88`
`stages`	Check this endpoint for all possibilities.	Filter season stages based on stage IDs	`&filters=stageStages:stageIDS` `&filters=stageStages:77457866`
`rounds`	Check this endpoint for all possibilities.	Filter season rounds based on round IDs	`&filters=roundRounds:roundIDS` `&filters=roundRounds:290018`
`topscorers`	Check this endpoint for all possibilities.	Filter season topscorers based on type IDs	`&include=topscorers&filters=seasonTopscorerTypes:TypeIDs` `&include=topscorers&filters=seasonTopscorerTypes:208`

{% endtab %} {% endtabs %} ### Filters More information on how to use filters can be found in our tutorials on how to [filter](https://docs.sportmonks.com/football2/api/request-options/filtering). If you want more information on which filters to use you can check out the following [endpoint](/v3/core-api/endpoints/filters/get-all-entity-filters): {% hint style="info" %} ``` https://api.sportmonks.com/v3/my/filters/entity?api_token=YOUR_TOKEN ``` {% endhint %} ### Pagination NO ### Include depth You can use a total of `3` nested includes on this endpoint ### Include options [`sport`](https://docs.sportmonks.com/v3/core-api/) [`league`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#league) [`teams`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#team) [`stages`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#stage) [`currentStage`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#stage) [`fixtures`](/v3/endpoints-and-entities/entities/fixture#fixture) [`groups`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#group) [`statistics`](/v3/endpoints-and-entities/entities/statistic#seasonstatistic) [`topscorers`](/v3/endpoints-and-entities/entities/standing-and-topscorer#topscorers) ### **Related Entities** Get an overview and explanation of all the fields returned in the API response. The related entities for the seasons endpoints are: * [Season](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season) ### Postman We also offer detailed postman documentation with examples and a complete up-to-date version of all our endpoints. Below is a button that lets you fork the collection or import it. \ [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316?action=collection%2Ffork\&collection-url=entityId%3D11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316%26entityType%3Dcollection%26workspaceId%3D17c720d0-d97b-42a9-9ea7-23260ed53ddf) ### Code Example {% tabs %} {% tab title="Ruby" %} ```ruby require "uri" require "net/http" url = URI("https://api.sportmonks.com/v3/football/seasons/{ID}?api_token=YOUR_TOKEN") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Get.new(url) response = https.request(request) puts response.read_body ``` {% endtab %} {% tab title="Python" %} ```python import http.client conn = http.client.HTTPSConnection("api.sportmonks.com") payload = '' headers = {} conn.request("GET", "/v3/football/seasons/{ID}?api_token=YOUR_TOKEN", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) ``` {% endtab %} {% tab title="PHP" %} ```php 'https://api.sportmonks.com/v3/football/seasons/{ID}?api_token=YOUR_TOKEN', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', )); $response = curl_exec($curl); curl_close($curl); echo $respons ``` {% endtab %} {% tab title="Java" %} ```java OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://api.sportmonks.com/v3/football/seasons/{ID}?api_token=YOUR_TOKEN") .method("GET", null) .build(); Response response = client.newCall(request).execute(); ``` {% endtab %} {% tab title="Node.js" %} ``` var unirest = require('unirest'); var req = unirest('GET', 'https://api.sportmonks.com/v3/football/seasons/{ID}?api_token=YOUR_TOKEN') .end(function (res) { if (res.error) throw new Error(res.error); console.log(res.raw_body); }); ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://api.sportmonks.com/v3/football/seasons/{ID}?api_token=YOUR_TOKEN" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %} # GET Seasons by Team ID Returns seasons by team ID. {% tabs %} {% tab title="Base URL" %} ```javascript https://api.sportmonks.com/v3/football/seasons/teams/{ID} ``` {% endtab %} {% tab title="Example Response" %} ```json "data": [ { "id": 1937, "sport_id": 1, "league_id": 501, "tie_breaker_rule_id": 169, "name": "2015/2016", "finished": true, "pending": false, "is_current": false, "starting_at": "2015-08-01", "ending_at": "2016-05-15", "standings_recalculated_at": "2023-02-13 15:48:33", "games_in_current_week": false }, { "id": 1936, "sport_id": 1, "league_id": 501, "tie_breaker_rule_id": 169, "name": "2014/2015", "finished": true, "pending": false, "is_current": false, "starting_at": "2014-08-09", "ending_at": "2015-05-24", "standings_recalculated_at": "2023-02-13 15:48:34", "games_in_current_week": false }, ``` {% endtab %} {% tab title="Field Description" %}

Field	Description	Type
id	Refers to the id of the season	integer
sport_id	Refers to the sport of the season	integer
league_id	Refers to the league of the season	integer
tie_breaker_rule_id	Refers to the type of tie-breaker rule used to determine the season winner	integer
name	The name of the season	string
finished	Indicates if the season finished or not	integer
pending	Indicates if the season is pending or not	integer
is_current	Indicates if the season is the current season or not	integer
standing_method	Returns the standing calculation used in the season	string
starting_at	The starting date of the season	string
ending_at	The end date of the season	string

{% endtab %} {% endtabs %} {% tabs %} {% tab title="Query Parameters" %}

Name	Required?	Description
`api_token`	YES Another option is to provide the API token in the header.	Your unique API token. Ex. ?api_token=YOUR_TOKEN
`include`	NO	Enrich the API response with more data by using includes. Ex. &include=participants;events
`select`	NO	Select specific fields on the base entity. Read how to select fields in our tutorial.
`filters`	NO	Filter the API response on multiple related entities. There are static filters and dynamic filters. Please find the possibilities in the Static and Dynamic Filter tab.
`locale`	NO	Translate name fields of the API Response in your selected language. Find more information and which languages are available on our translations page.

Static filters	Available on Entity	Description	Example
N/A	N/A	Not available for this endpoint.	`N/A`

{% endtab %} {% tab title="Dynamic Filters" %} The **dynamic filters** are based on entities and includes. Each dynamic filter uses an entity to filter on and one entity to apply the filter on. Below are examples with explanations of how filters are set up. For more information, please look at our[ Filters page](/v3/api/request-options/filtering). {% hint style="info" %} Using an include? Check their respective filters on their entity page. For example if you use `&include=fixtures`, you can apply [fixture-related filters](/v3/endpoints-and-entities/entities/fixture#fixture-entity-filters). {% endhint %}

Dynamic Filters	Available on Entity	Description	Examples
`types`	Statistics, Events, Lineup, and way more. Check this endpoint for all possibilities.	Filter the season statistics on a selection of types separated by a comma.	`&include=statistics&filters=seasonstatisticTypes:TypeIDs` `&include=statistics&filters=seasonstatisticTypes:52,88`
`stages`	Check this endpoint for all possibilities.	Filter season stages based on stage IDs	`&filters=stageStages:stageIDS` `&filters=stageStages:77457866`
`rounds`	Check this endpoint for all possibilities.	Filter season rounds based on round IDs	`&filters=roundRounds:roundIDS` `&filters=roundRounds:290018`
`topscorers`	Check this endpoint for all possibilities.	Filter season topscorers based on type IDs	`&include=topscorers&filters=seasonTopscorerTypes:TypeIDs` `&include=topscorers&filters=seasonTopscorerTypes:208`

{% endtab %} {% endtabs %} ### Filters More information on how to use filters can be found on our tutorials on how to [filter](https://docs.sportmonks.com/football2/api/request-options/filtering). If you want more information on which filters to use you can check out the following [endpoint](/v3/core-api/endpoints/filters/get-all-entity-filters): {% hint style="info" %} ``` https://api.sportmonks.com/v3/my/filters/entity?api_token=YOUR_TOKEN ``` {% endhint %} ### Pagination NO ### Include depth You can use a total of `3` nested includes on this endpoint ### Include options [`sport`](https://docs.sportmonks.com/v3/core-api/) [`league`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#league) [`teams`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#team) [`stages`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#stage) [`currentStage`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#stage) [`fixtures`](/v3/endpoints-and-entities/entities/fixture#fixture) [`groups`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#group) [`statistics`](/v3/endpoints-and-entities/entities/statistic#seasonstatistic) [`topscorers`](/v3/endpoints-and-entities/entities/standing-and-topscorer#topscorers) ### **Related Entities:** Get an overview and explanation of all the fields returned in the API response. The related entities for the seasons endpoints are: * [Season](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season) ### Postman We also offer detailed postman documentation with examples and a complete up-to-date version of all our endpoints. Below is a button that lets your fork the collection or import it. \ [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316?action=collection%2Ffork\&collection-url=entityId%3D11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316%26entityType%3Dcollection%26workspaceId%3D17c720d0-d97b-42a9-9ea7-23260ed53ddf) ### Code Example {% tabs %} {% tab title="Ruby" %} ```ruby require "uri" require "net/http" url = URI("https://api.sportmonks.com/v3/football/seasons/{ID}?api_token=YOUR_TOKEN") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Get.new(url) response = https.request(request) puts response.read_body ``` {% endtab %} {% tab title="Python" %} ```python import http.client conn = http.client.HTTPSConnection("api.sportmonks.com") payload = '' headers = {} conn.request("GET", "/v3/football/seasons/{ID}?api_token=YOUR_TOKEN", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) ``` {% endtab %} {% tab title="PHP" %} ```php 'https://api.sportmonks.com/v3/football/seasons/{ID}?api_token=YOUR_TOKEN', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', )); $response = curl_exec($curl); curl_close($curl); echo $respons ``` {% endtab %} {% tab title="Java" %} ```java OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://api.sportmonks.com/v3/football/seasons/{ID}?api_token=YOUR_TOKEN") .method("GET", null) .build(); Response response = client.newCall(request).execute(); ``` {% endtab %} {% tab title="Node.js" %} ``` var unirest = require('unirest'); var req = unirest('GET', 'https://api.sportmonks.com/v3/football/seasons/{ID}?api_token=YOUR_TOKEN') .end(function (res) { if (res.error) throw new Error(res.error); console.log(res.raw_body); }); ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://api.sportmonks.com/v3/football/seasons/{ID}?api_token=YOUR_TOKEN" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %} # GET Seasons by Search by Name Returns all the seasons that match your search query. {% tabs %} {% tab title="Base URL" %} ```javascript https://api.sportmonks.com/v3/football/seasons/search/{searchQuery} ``` {% endtab %} {% tab title="Example Response" %} ```json { "data": [ { "id": 18334, "sport_id": 1, "league_id": 271, "tie_breaker_rule_id": 169, "name": "2021/2022", "finished": true, "pending": false, "is_current": false, "starting_at": "2021-07-16", "ending_at": "2022-05-29", "standings_recalculated_at": "2023-02-13 15:55:31", "games_in_current_week": false }, { "id": 18369, "sport_id": 1, "league_id": 501, "tie_breaker_rule_id": 169, "name": "2021/2022", "finished": true, "pending": false, "is_current": false, "starting_at": "2021-07-31", "ending_at": "2022-05-15", "standings_recalculated_at": "2023-02-13 15:55:32", "games_in_current_week": false }, ``` {% endtab %} {% tab title="Field Description" %}

Field	Description	Type
id	Refers to the id of the season	integer
sport_id	Refers to the sport of the season	integer
league_id	Refers to the league of the season	integer
tie_breaker_rule_id	Refers to the type of tie-breaker rule used to determine the season winner	integer
name	The name of the season	string
finished	Indicates if the season finished or not	integer
pending	Indicates if the season is pending or not	integer
is_current	Indicates if the season is the current season or not	integer
standing_method	Returns the standing calculation used in the season	string
starting_at	The starting date of the season	string
ending_at	The end date of the season	string

{% endtab %} {% endtabs %} {% tabs %} {% tab title="Query Parameters" %}

Name	Required?	Description
`api_token`	YES Another option is to provide the API token in the header.	Your unique API token. Ex. ?api_token=YOUR_TOKEN
`include`	NO	Enrich the API response with more data by using includes. Ex. &include=participants;events
`select`	NO	Select specific fields on the base entity. Read how to select fields in our tutorial.
`filters`	NO	Filter the API response on multiple related entities. There are static filters and dynamic filters. Please find the possibilities in the Static and Dynamic Filter tab.
`locale`	NO	Translate name fields of the API Response in your selected language. Find more information and which languages are available on our translations page.

Static filters	Available on Entity	Description	Example
N/A	N/A	Not available for this endpoint.	`N/A`

{% endtab %} {% tab title="Dynamic Filters" %} The **dynamic filters** are based on entities and includes. Each dynamic filter uses an entity to filter on and one entity to apply the filter on. Below are examples with explanations of how filters are set up. For more information, please look at our[ Filters page](/v3/api/request-options/filtering). {% hint style="info" %} Using an include? Check their respective filters on their entity page. For example if you use `&include=fixtures`, you can apply [fixture-related filters](/v3/endpoints-and-entities/entities/fixture#fixture-entity-filters). {% endhint %}

Dynamic Filters	Available on Entity	Description	Examples
`types`	Statistics, Events, Lineup, and way more. Check this endpoint for all possibilities.	Filter the season statistics on a selection of types separated by a comma.	`&include=statistics&filters=seasonstatisticTypes:TypeIDs` `&include=statistics&filters=seasonstatisticTypes:52,88`
`leagues`	Fixtures, Seasons, Standings, and way more. Check this endpoint for all possibilities.	Filter the seasons based on leagues.	`&include=league&&filters=seasonLeagues:leagueIDs` `&include=league&&filters=seasonLeagues:2,8`
`stages`	Check this endpoint for all possibilities.	Filter season stages based on stage IDs	`&filters=stageStages:stageIDS` `&filters=stageStages:77457866`
`rounds`	Check this endpoint for all possibilities.	Filter season rounds based on round IDs	`&filters=roundRounds:roundIDS` `&filters=roundRounds:290018`
`topscorers`	Check this endpoint for all possibilities.	Filter season topscorers based on type IDs	`&include=topscorers&filters=seasonTopscorerTypes:TypeIDs` `&include=topscorers&filters=seasonTopscorerTypes:208`

Parameter	Required	Description	Example
`order`	No	Returns seasons ordered by id (`asc` or `desc`). Defaults to asc	&order=desc
`per_page`	No	The amount of results to return per page (max 50.). Defaults to 25.	&per_page=30
`page`	No	You can paginate using the `has_more` parameter to determine if you can still propagate through the results.	&page=2

### Include depth You can use a total of `3` nested includes on this endpoint ### Include options [`sport`](https://docs.sportmonks.com/v3/core-api/) [`league`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#league) [`teams`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#team) [`stages`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#stage) [`currentStage`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#stage) [`fixtures`](/v3/endpoints-and-entities/entities/fixture#fixture) [`groups`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#group) [`statistics`](/v3/endpoints-and-entities/entities/statistic#seasonstatistic) [`topscorers`](/v3/endpoints-and-entities/entities/standing-and-topscorer#topscorers) ### **Related Entities:** Get an overview and explanation of all the fields returned in the API response. The related entities for the seasons endpoints are: * [Season](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season) ### Postman We also offer detailed postman documentation with examples and a complete up-to-date version of all our endpoints. Below is a button that lets your fork the collection or import it. \ [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316?action=collection%2Ffork\&collection-url=entityId%3D11949411-c7a3a0a0-b5c5-4109-9bf6-f430fec65316%26entityType%3Dcollection%26workspaceId%3D17c720d0-d97b-42a9-9ea7-23260ed53ddf) ### Code Example {% tabs %} {% tab title="Ruby" %} ```ruby require "uri" require "net/http" url = URI("https://api.sportmonks.com/v3/football/seasons/search/{searchQuery}?api_token=YOUR_TOKEN") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Get.new(url) response = https.request(request) puts response.read_body ``` {% endtab %} {% tab title="Python" %} ```python import http.client conn = http.client.HTTPSConnection("api.sportmonks.com") payload = '' headers = {} conn.request("GET", "/v3/football/seasons/search/{searchQuery}?api_token=YOUR_TOKEN", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) ``` {% endtab %} {% tab title="PHP" %} ```php 'https://api.sportmonks.com/v3/football/seasons/search/{searchQuery}?api_token=YOUR_TOKEN', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', )); $response = curl_exec($curl); curl_close($curl); echo $respons ``` {% endtab %} {% tab title="Java" %} ```java OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://api.sportmonks.com/v3/football/seasons/search/{searchQuery}?api_token=YOUR_TOKEN") .method("GET", null) .build(); Response response = client.newCall(request).execute(); ``` {% endtab %} {% tab title="Node.js" %} ``` var unirest = require('unirest'); var req = unirest('GET', 'https://api.sportmonks.com/v3/football/seasons/search/{searchQuery}?api_token=YOUR_TOKEN') .end(function (res) { if (res.error) throw new Error(res.error); console.log(res.raw_body); }); ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://api.sportmonks.com/v3/football/seasons/search/{searchQuery}?api_token=YOUR_TOKEN" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %} # GET Brackets by Season ID The Tournament Brackets endpoint provides a structured view of knockout stage tournament brackets, making it easy to display elimination rounds, progression paths, and matchup hierarchies in your application. {% hint style="info" %} **Available for:** Knockout stages only (stages with `type_id: 224`) with placeholder and match numbers available. **Use Cases:** World Cup {% endhint %} Tournament brackets organise knockout fixtures into a tree structure, showing how winners advance through rounds until a champion is crowned. This endpoint automatically structures the data with fixture progression paths (edges) that define how teams move through the bracket. ### When to use this endpoint Use the brackets endpoint when you need to: * Display a complete knockout bracket visualisation * Show tournament progression from Round of 32 → Round of 16 → Quarter-finals → Semi-finals → 3rd Place → Final * Track which teams advance to which matches based on match outcomes * Build interactive bracket interfaces with automatic progression logic {% hint style="info" %} **Knockout Stages Only** This endpoint only returns data for knockout stages (elimination rounds). Group stage fixtures should be accessed via the standard fixtures endpoint. {% endhint %} ### Endpoint ```bash GET https://api.sportmonks.com/v3/football/seasons/{season_id}/brackets ``` #### Parameters | Parameter | Type | Required | Description | | ----------- | ------- | -------- | ---------------------------------------------- | | `season_id` | integer | Yes | The season ID (e.g., 26618 for World Cup 2026) | | `api_token` | string | Yes | Your API authentication token | | `include` | string | No | Related data to include (see Includes section) | #### Example Request ```bash GET https://api.sportmonks.com/v3/football/seasons/26618/brackets?api_token=YOUR_TOKEN ``` ### Response Structure The response contains two main components: `stages` (fixtures organised by knockout round) and `edges` (progression paths between fixtures). ```json { "data": { "stages": [ { "stage_id": 77479086, "stage_name": "16th Finals", "fixtures": [ { "id": 19606960, "sport_id": 1, "league_id": 732, "season_id": 26618, "stage_id": 77479086, "state_id": 1, "venue_id": 343444, "name": "2nd position Group A vs 2nd position Group B", "starting_at": "2026-06-28 19:00:00", "result_info": null, "leg": "1/1", "details": "Match 73", "length": 90, "placeholder": true, "starting_at_timestamp": 1782673200 } ] }, { "stage_id": 77479087, "stage_name": "8th Finals", "fixtures": [ { "id": 19606967, "name": "Winner Match 74 vs Winner Match 77", "starting_at": "2026-07-04 21:00:00", "details": "Match 89", "placeholder": true } ] }, { "stage_id": 77479088, "stage_name": "Quarter-finals", "fixtures": [...] }, { "stage_id": 77479089, "stage_name": "Semi-finals", "fixtures": [...] }, { "stage_id": 77479091, "stage_name": "3rd Place Final", "fixtures": [ { "id": 19606976, "name": "Loser Semi-final 1 vs Loser Semi-final 2", "starting_at": "2026-07-18 21:00:00", "details": "Match 103", "placeholder": true } ] }, { "stage_id": 77479090, "stage_name": "Final", "fixtures": [ { "id": 19606975, "name": "Winner Semi-final 1 vs Winner Semi-final 2", "starting_at": "2026-07-19 19:00:00", "details": "Match 104", "placeholder": true } ] } ], "edges": [ { "id": 9, "season_id": 26618, "child_fixture_id": 19606975, "child_slot": "home", "parent_fixture_id": 19606974, "parent_outcome": "winner" }, { "id": 10, "season_id": 26618, "child_fixture_id": 19606975, "child_slot": "away", "parent_fixture_id": 19606973, "parent_outcome": "winner" }, { "id": 11, "season_id": 26618, "child_fixture_id": 19606976, "child_slot": "home", "parent_fixture_id": 19606974, "parent_outcome": "loser" }, { "id": 12, "season_id": 26618, "child_fixture_id": 19606976, "child_slot": "away", "parent_fixture_id": 19606973, "parent_outcome": "loser" } ] }, "subscription": [...], "rate_limit": { "resets_in_seconds": 3600, "remaining": 2999, "requested_entity": "Fixture" } } ``` #### Response Fields **Stages Array** | Field | Type | Description | | ------------ | ------- | --------------------------------------------------------- | | `stage_id` | integer | Unique stage identifier | | `stage_name` | string | Name of the knockout round (e.g., "Semi-finals", "Final") | | `fixtures` | array | All fixtures in this knockout round | **Fixture Object** | Field | Type | Description | | ------------- | ----------- | ------------------------------------------------ | | `id` | integer | Unique fixture ID | | `stage_id` | integer | Stage this fixture belongs to | | `name` | string | Fixture name (shows teams/progression) | | `starting_at` | string | Match kickoff time (UTC) | | `details` | string | Match number identifier (e.g., "Match 73") | | `placeholder` | boolean | `true` if teams are not yet determined | | `state_id` | integer | Match state (1=Not Started, 5=Finished, etc.) | | `venue_id` | integer | Stadium identifier | | `leg` | string | "1/1" for single-leg knockout matches | | `result_info` | string/null | Result description (e.g., "Won after penalties") | **Edges Array** The `edges` array defines progression paths between fixtures: | Field | Type | Description | | ------------------- | ------- | ------------------------------------------------ | | `id` | integer | Unique edge identifier | | `season_id` | integer | Season identifier | | `child_fixture_id` | integer | Fixture that receives the advancing team | | `child_slot` | string | Position in child fixture (`"home"` or `"away"`) | | `parent_fixture_id` | integer | Fixture that determines the advancing team | | `parent_outcome` | string | Which team advances (`"winner"` or `"loser"`) | {% hint style="info" %} **Understanding Edges** Edges create the bracket tree structure. Each edge says: "The **winner/loser** of Match X goes to the **home/away** slot of Match Y." For example, the Final receives the **winners** of both Semi-finals, whilst the 3rd Place Final receives the **losers** of both Semi-finals. {% endhint %} ### Understanding bracket structure #### Stages organisation Stages are returned in the order they appear in the response (not sorted by chronological order): ``` 16th Finals → Round of 32 (16 matches) 8th Finals → Round of 16 (8 matches) Quarter-finals → Quarter-finals (4 matches) Semi-finals → Semi-finals (2 matches) 3rd Place Final → 3rd Place playoff (1 match) Final → Championship match (1 match) ``` #### Placeholder Fixtures Before teams are determined, fixtures have `placeholder: true` and descriptive names: ```json { "name": "Winner Match 74 vs Winner Match 77", "placeholder": true } ``` After matches are played and teams advance: ```json { "name": "Brazil vs Argentina", "placeholder": false } ``` Always check `placeholder` before displaying team information. #### Progression Paths via Edges Edges define how teams move through the bracket: **Example: Final receives winners from both Semi-finals** ```json // Semi-final 1 winner → Final home slot { "child_fixture_id": 19606975, // Final "child_slot": "home", "parent_fixture_id": 19606974, // Semi-final 1 "parent_outcome": "winner" } // Semi-final 2 winner → Final away slot { "child_fixture_id": 19606975, // Final "child_slot": "away", "parent_fixture_id": 19606973, // Semi-final 2 "parent_outcome": "winner" } ``` **Example: 3rd Place Final receives losers from both Semi-finals** ```json // Semi-final 1 loser → 3rd Place home slot { "child_fixture_id": 19606976, // 3rd Place Final "child_slot": "home", "parent_fixture_id": 19606974, // Semi-final 1 "parent_outcome": "loser" } // Semi-final 2 loser → 3rd Place away slot { "child_fixture_id": 19606976, // 3rd Place Final "child_slot": "away", "parent_fixture_id": 19606973, // Semi-final 2 "parent_outcome": "loser" } ``` ### Includes Add includes to get complete fixture data with participants, scores, and match details: ``` GET /v3/football/seasons/{season_id}/brackets ?api_token=YOUR_TOKEN &include=stages.fixtures.participants;stages.fixtures.state;stages.fixtures.scores ``` #### Available Includes [`sport`](https://docs.sportmonks.com/v3/core-api/) [`round`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#round) [`stage`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#stage) [`group`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#group) [`aggregate`](/v3/endpoints-and-entities/entities/fixture#aggregate) [`league`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#league) [`season`](/v3/endpoints-and-entities/entities/league-season-schedule-stage-and-round#season)[`coaches`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#coach) [`tvStations`](/v3/endpoints-and-entities/entities/other#tvstation) [`venue`](/v3/endpoints-and-entities/entities/other#venue) [`state`](/v3/endpoints-and-entities/entities/other#state) [`weatherReport`](/v3/endpoints-and-entities/entities/other#weatherreport) [`lineups`](/v3/endpoints-and-entities/entities/fixture#lineup) [`events`](/v3/endpoints-and-entities/entities/fixture#event) [`timeline`](/v3/endpoints-and-entities/entities/fixture#event) [`comments`](/v3/endpoints-and-entities/entities/other#commentary) [`trends`](/v3/endpoints-and-entities/entities/statistic#trend) [`statistics`](/v3/endpoints-and-entities/entities/statistic#fixturestatistic) [`periods`](/v3/endpoints-and-entities/entities/fixture#period) [`participants` ](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#team)[`odds`](/v3/endpoints-and-entities/entities/odd-and-prediction#odd)[`premiumOdds`](https://docs.sportmonks.com/football/endpoints-and-entities/entities/odd-and-prediction#premium-odd) [`inplayOdds`](/v3/endpoints-and-entities/entities/odd-and-prediction#inplayodd) [`prematchNews`](/v3/endpoints-and-entities/entities/other#news) [`postmatchNews`](/v3/endpoints-and-entities/entities/other#news) [`metadata`](/v3/endpoints-and-entities/entities/other#metadata) [`sidelined`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#sidelined)[`predictions`](/v3/endpoints-and-entities/entities/odd-and-prediction#prediction-valuebet) [`referees`](/v3/endpoints-and-entities/entities/team-player-squad-coach-and-referee#referees) [`formations`](/v3/endpoints-and-entities/entities/fixture#formation) [`ballCoordinates`](/v3/endpoints-and-entities/entities/fixture#ballcoordinate) [`scores`](/v3/endpoints-and-entities/entities/fixture#score) [`xGFixture`](/v3/endpoints-and-entities/entities/expected) [`pressure`](/v3/tutorials-and-guides/tutorials/includes/pressure-index) `expectedLineups` #### Example with full includes ```bash GET https://api.sportmonks.com/v3/football/seasons/26618/brackets ?api_token=YOUR_TOKEN &include=scores;participants;lineups ``` ### Bracket visualisation The brackets endpoint returns data that can be visualised as a tournament tree:

### Frontend Examples {% tabs %} {% tab title="React" %} ```javascript import { useState } from 'react'; function TournamentBracket({ seasonId, apiToken }) { const [bracketData, setBracketData] = useState(null); const [loading, setLoading] = useState(false); const [error, setError] = useState(null); const fetchBracket = async () => { setLoading(true); setError(null); try { const response = await fetch( `https://api.sportmonks.com/v3/football/seasons/${seasonId}/brackets` + `?api_token=${apiToken}` + `&include=participants;state` ); if (!response.ok) { throw new Error(`HTTP error! status: ${response.status}`); } const data = await response.json(); setBracketData(data.data); } catch (err) { setError(err.message); console.error('Failed to fetch bracket:', err); } finally { setLoading(false); } }; if (loading) return

Loading bracket...

; if (error) return

Error: {error}

; if (!bracketData) { return ; } return (

Knockout Bracket

{bracketData.stages.map(stage => (

{stage.stage_name}

{stage.fixtures.map(fixture => (

{fixture.details} {fixture.name}

{fixture.participants?.map(p => (

{p.participant?.name || 'TBD'} {p.meta?.winner && ' 🏆'}

))}

{new Date(fixture.starting_at).toLocaleString()}

))}

Progression Paths

{bracketData.edges.length} advancement paths defined

); } export default TournamentBracket; ``` {% endtab %} {% tab title="Vue" %} ```vue ``` {% endtab %} {% tab title="Svelte" %} ```svelte

{#if !bracketData} {/if} {#if loading}

Loading bracket...

{:else if error}

Error: {error}

{:else if bracketData}

Knockout Bracket

{#each bracketData.stages as stage}

{stage.stage_name}

{#each stage.fixtures as fixture}

{fixture.details} {fixture.name}

{#each fixture.participants || [] as participant}

{participant.participant?.name || 'TBD'} {#if participant.meta?.winner}🏆{/if}

{/each}

{new Date(fixture.starting_at).toLocaleString()}

{/each}

{/each} {/if}

``` {% endtab %} {% tab title="Angular" %} ```angular-ts // tournament-bracket.component.ts import { Component, Input } from '@angular/core'; import { HttpClient, HttpErrorResponse } from '@angular/common/http'; interface BracketStage { stage_id: number; stage_name: string; fixtures: any[]; } interface BracketData { stages: BracketStage[]; edges: any[]; } @Component({ selector: 'app-tournament-bracket', templateUrl: './tournament-bracket.component.html', styleUrls: ['./tournament-bracket.component.css'] }) export class TournamentBracketComponent { @Input() seasonId!: number; @Input() apiToken!: string; bracketData: BracketData | null = null; loading = false; error: string | null = null; constructor(private http: HttpClient) {} fetchBracket(): void { this.loading = true; this.error = null; const url = `https://api.sportmonks.com/v3/football/seasons/${this.seasonId}/brackets` + `?api_token=${this.apiToken}` + `&include=participants;state`; this.http.get<{ data: BracketData }>(url).subscribe({ next: (response) => { this.bracketData = response.data; this.loading = false; }, error: (err: HttpErrorResponse) => { this.error = err.message; this.loading = false; console.error('Failed to fetch bracket:', err); } }); } } ``` {% endtab %} {% endtabs %} ### Common use cases #### 1. Display complete tournament bracket Fetch all knockout matches organised by stage: ```javascript const response = await fetch( `/v3/football/seasons/26618/brackets` + `?api_token=${token}` + `&include=participants;state` ); const { data } = await response.json(); // Access stages data.stages.forEach(stage => { console.log(`${stage.stage_name}: ${stage.fixtures.length} matches`); }); ``` #### 2. Find Where a Team Advances Use edges to determine the next match for a winner: ```javascript function findNextMatch(bracketData, currentFixtureId, outcome = 'winner') { const edge = bracketData.edges.find(e => e.parent_fixture_id === currentFixtureId && e.parent_outcome === outcome ); if (!edge) return null; // Find the child fixture in stages for (const stage of bracketData.stages) { const nextFixture = stage.fixtures.find(f => f.id === edge.child_fixture_id); if (nextFixture) { return { fixture: nextFixture, slot: edge.child_slot, stage: stage.stage_name }; } } return null; } // Example: Where does the winner of Semi-final 1 go? const nextMatch = findNextMatch(bracketData, 19606974, 'winner'); console.log(`Winner advances to ${nextMatch.stage} as ${nextMatch.slot} team`); // Output: "Winner advances to Final as home team" ``` #### 3. Build bracket tree structure Organise matches into a hierarchical tree: ```javascript function buildBracketTree(bracketData) { const fixtureMap = new Map(); // Index all fixtures by ID bracketData.stages.forEach(stage => { stage.fixtures.forEach(fixture => { fixtureMap.set(fixture.id, { ...fixture, stage_name: stage.stage_name, parents: [], children: [] }); }); }); // Build relationships from edges bracketData.edges.forEach(edge => { const child = fixtureMap.get(edge.child_fixture_id); const parent = fixtureMap.get(edge.parent_fixture_id); if (child && parent) { child.parents.push({ fixture: parent, outcome: edge.parent_outcome, slot: edge.child_slot }); parent.children.push({ fixture: child, outcome: edge.parent_outcome }); } }); return fixtureMap; } ``` #### 4. Filter by stage Display only specific knockout rounds: ```javascript // Get only Final and 3rd Place matches const finalStages = bracketData.stages.filter(stage => ['Final', '3rd Place Final'].includes(stage.stage_name) ); finalStages.forEach(stage => { console.log(`${stage.stage_name}:`); stage.fixtures.forEach(f => console.log(` - ${f.name}`)); }); ``` #### 5. Check Match Status Identify which matches have been played: ```javascript function getMatchStatus(bracketData) { const status = { notStarted: [], completed: [], live: [] }; bracketData.stages.forEach(stage => { stage.fixtures.forEach(fixture => { if (fixture.state_id === 1) { status.notStarted.push(fixture); } else if (fixture.state_id === 5) { status.completed.push(fixture); } else if (fixture.state_id === 2 || fixture.state_id === 3) { status.live.push(fixture); } }); }); return status; } ``` ### Best Practices **Caching strategy** * Cache bracket structure for 1 hour when no matches are live * Reduce to 5 minutes during live knockout matches * Cache permanently once tournament is complete {% endhint %} **Check placeholder status** Always verify `fixture.placeholder` before displaying team names. Placeholder fixtures indicate matches where participants aren't yet determined. {% endhint %} **Optimise includes** Only request includes you'll display. For a simple bracket view, `stages.fixtures.participants` and `stages.fixtures.state` are sufficient. Add `stages.fixtures.scores` for live updates. {% endhint %} #### Recommended includes **Minimal bracket view:** ``` &include=participants;state;venue ``` **Full match details:** ``` &include=participants;state;venus;lineups ``` **Live updates:** ``` &include=scores;state;lineups;statistics ``` ### Error Handling #### No knockout stages If a season has no knockout stages, the response will have empty arrays: ```json { "data": { "stages": [], "edges": [] } } ``` **Solution:** Verify the season has knockout stages before requesting brackets. #### Missing edges If edges data is incomplete, bracket progression cannot be determined: ```json { "data": { "stages": [...], "edges": [] } } ``` **Solution:** Contact support if edges are missing for a tournament that has defined progression rules. ### Rate limits The brackets endpoint counts against the **Fixture** entity rate limit: * **Standard limit:** 3,000 requests per hour * **Monitor:** Check `x-ratelimit-remaining` header * **Best practice:** Cache bracket data to reduce API calls ```javascript // Check rate limit in response const remaining = response.headers.get('x-ratelimit-remaining'); console.log(`Rate limit remaining: ${remaining}`); ``` ### Related endpoints * [Fixtures](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/fixtures) - Individual match data * [Seasons](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/seasons) - Tournament structure * [Stages](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/stages) - Stage information * [Standings](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/standings) - Group stage tables *** {% hint style="info" %} **New Feature** The Tournament Brackets endpoint is a new addition to Sportmonks API v3. Feedback and suggestions are welcome at . {% endhint %} # Statistics These endpoints allow you to retrieve statistics per season, round, and stage. Use one of our 3 statistics endpoints. Per endpoint, you can find the details, including base URL, parameters, includes and more. * **GET Season Statistics by Participant:** returns statistics by season for the given participant. * **GET Stage Statistics:** returns statistics by the given stage ID. * **GET Round Statistics:** returns statistics by the given round ID. You can find an overview of all the statistics we offer below.


Statistics	You can find an overview of all the statistics we offer here.	https://docs.google.com/spreadsheets/d/1dNZqVPJznDtUAjU8110nU_5Ecukle27IRwDXqXqP_P0/edit?usp=sharing

--- [Next Page](/v3/llms-full.txt/1)

Knockout Bracket

{stage.stage_name}

Progression Paths

Knockout Bracket

{{ stage.stage_name }}

Knockout Bracket

{stage.stage_name}