20.0.55 - 2022-01-14

Change

With immediately effect it's not possible anymore to change the pagination default on the following endpoints:

• fixtures/between{date1}/{date2}

• fixtures//between/{startDate}/{endDate}/{teamId}

2.0.54 - 2021-08-02

Added

• Added new weather types. You can check an overview of all possible outcomes on our Statuses and Defintion page.

• Added the opportunity to retrieve all bookmakers by Fixture ID.

2.0.54 - 2021-07-05

Added

• Added 'is_friendly' property on league related responses or includes. This indicates if the league is friendly.

2.0.53 - 2021-06-23

Added

• Added a new filter on the Head2Head endpoint. You can now filter between dates: &between= This gives you the opportunity to retrieve all past (or future) matches between two teams.

• Added the Rivals endpoint and include. You can now include rivals on the teams endpoint to retrieve all the rivals of one team.

2.0.52 - 2021-06-06

Added

• Added the opportunity to retrieve all fixtures by Market ID. This allows you to gather all fixtures that have a specific odd market available.

2.0.51 - 2021-05-06

Added

• Added the News API (BETA) for the English Premier League and European Championship.

• Added 20 new leagues, including the UEFA Conference League (ID: 2286). You can check all leagues on our coverage page.

2.0.51 - 2021-04-06

Added

• Added the official match numbers of the European Championship fixtures in the details field.

• Added a property on both fixture and team responses called is_placeholder. This property indicates if the resource is used to display dummy data. The false of this property will always be a boolean value. An example where this becomes useful: Imagine you want to load the complete schedule of the European Championship and display this in a nice visual. You would need the complete schedule including knockout games which haven't yet been determined when the season starts. This property tells you that there the data is not final or is used for placeholder purposes. The id of a fixture will remain the same when real data is merged to it.

• Added a property called is_value on the valuebet responses. This property indicates if a value still provides value. When this is set to false you should remove the value bet from your system.

Welcome to the documentation overview of Sportmonks' APIs. We'll briefly inform you about the features of our API and then you can explore our documentation for yourself.

Quick starts

Features of our APIs

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.

If you want to get started right away, great! Head over to our Getting Started section, where you'll create your own API token and create your first request.

Else, you can refer to our Documentation Organization section, to see what's relevant for you.

Are you here for our API References Guide? No problem here's a link and enjoy! For any technical questions, you can email our support team [email protected].

The Continents endpoint helps you assign Countries and Leagues to the part of the world (Continent) they belong to. Available Continents are Europe, Asia, Africa, Oceania, North America and South America. Especially if you want to show many Leagues on your website/app, this might be a useful endpoint for you.

Welcome to the documentation page about Sportmonks’ documentation! Now that you have completed our, you can freely choose what you want to go through next! Our extensive API documentation consists of the following sections:

So, yes. This is indeed a documentation page about our documentation! Our documentation sections are classified based on our users' capabilities.

The , for instance, is mostly aimed at users without a technical/programming background. There, we show you basic requests and explain how you can use the many features of our API. The is aimed at more advanced users. Ideally, you'd have read through the tutorial section first before attempting to work yourself through the how-to guides. The how-to guides will show you how to send the right requests to get the API data you need for your own , or .

Finally, the API References, are the most common resources used by developers already familiar with APIs. We also provide our API references in .

This way, you'll know where and how to navigate through our massive documentation. Good luck!

Want to know more about who we are?

Nothing is better than a good rivalry! Do you want to be able to show the biggest rivalries and the hottest derby days? Think about 'The Old Firm' or ‘The Superclásico’ and 'The Merseyside Derby'. With this new Rivals Endpoint you will be able to show all rivals every club has.

Countries

The Countries endpoint provides you Country information like its Flag, IsoCode, Continent and other related Country information.

The Countries endpoint also helps you with assigning Leagues to the Country they belong to. If for example, you want to show the Leagues per Country on your website/app, this might be a useful endpoint for you by using the Leagues Include.

For most customers, the Leagues endpoint is the starting point. A request on this endpoint returns a response with all Leagues you have access to, based on the plan you are subscribed to.

The Leagues endpoint provides you League information like its ID, Name, Country, Coverage etc.

The endpoint is often used in combination with the Season or Seasons Includes. Where the Season include returns information about the active Season only, the Seasons Include returns information about all seasons available for the specific Leagues.

With the Teams endpoint you can find all Team Details you need. You can think of information about when the Team is founded, Logo, Team Name, Short Name etc.

But especially by using the right includes you can have the right Team details you need, like the Team Coach, Team Venues, Results, Upcoming Games, Team Stats and many more valuable Team details.

The Players endpoint provides you detailed Player information. With this endpoint you will be able to build complete Player Profiles.

By using for example the Stats include it is possible to see the progression of the Player over the current domestic season. Those are also available for historic Seasons, starting from 2017.

The Topscorers endpoint provides you accurate information about the Topscorers in Goals, Cards and Assists. The endpoint returns the top 25 players and they can all be included at once or separately per Type (Goals, Cards or Assists).

This Topscorers endpoint returns the Topscorers by Stage of the Season. If you want an aggregated Topscorer list, please use the Aggregated Topscorers by Season endpoint.

The Venue endpoint provides Venue information like Name, City, Capacity, Address and even a Venue image.

Leagues can be split up into Rounds representing a week a game is played in. With this endpoint we give you the ability to request data for a single Round as well as all Rounds of a Season.

The endpoint is often used in combination with includes like Results or Fixtures to show them based on Rounds.

The Fixture endpoint provides information about Games in particular Leagues. There are always two teams involved in a Fixture. For many customers, Fixtures is the main endpoint for their app/website. Be aware your access is limited to Fixtures of Leagues, available in the Plan you are subscribed to.

Responses of the Fixture endpoint are highly customizable because there are many Includes available to extend the response. Requests often start with the Includes localTeam and VisitorTeam. Events, Stats, Lineups, Comments, Trends etc. are often added as well.

Statistics can be retrieved by using adding &include=stats to your request URL. This include is available on multiple endpoints. For more in-depth information, you can use our and .

Statistics tutorial

At Sportmonks we have a lot of data, and you will find everything you need. The data is divided into match-, team-, season, player- and in-play (live) player statistics.

In the tutorial below, we will go through every option one by one.

Via the Livescore endpoint, you can obtain live data of Games of the current day and live data for In-Play Games. The Livescore endpoint provides real-time data about Game information and Events like Goals, Cards, Substitutions, Line-ups, In-Play Statistics etc.

For many customers, Livescores is the main endpoint for their app/website. Be aware your access is limited to games of the Leagues that are available in the plan you are subscribed to.

Responses of the Livescore endpoint are highly customizable because there are many Includes available to extend the response. There are always two teams involved in a Livescore Game. Requests often start with the Includes localTeam and visitorTeam. Events, Stats, Lineups, Comments, Trends etc. are often added to extend the response.

The Commentary endpoint can be used to request the Textual representation of actions taken place in the Game. Commentaries are marked as Important or Goal when they meet that criteria.

Video Highlights are links to videos posted on social media networks. It can contain videos of Goals, Cards or other Events. Sometimes a video compilation of events is provided.

Video Highlights is a community feature, which basically means we have no control over the availability of videos. So, we cannot guarantee the video you are looking for is available.

Highlights are often used as an Include for the Fixture endpoint, but you can use Fixture as an Include for the Highlight endpoint.

The Head 2 Head endpoint provides you all previous Games between two Teams. Because it is about Historical Fixtures, it is possible to add Includes like for example Events, Line-ups, Stats, Goals, Cards, Referee etc.

This Head 2 Head endpoint can give you a complete overview of the historical Games between two teams.

Standings represent the rankings of Teams in the different Leagues they participate in. Responses of the Standings endpoint can be returned in two formats, depending on the League setup. For ‘normal’ Leagues the response format is different compared to Cups.

If you have Cups and ‘normal’ Leagues in your plan, make sure you check out the response properly.

Odds are used to add betting functionality to your application. This endpoint can be used for Pre-match Odds, we do have an endpoint for (live) as well.

We offer the ability to request Odds by Fixture, by Fixture And Bookmaker or by Fixture And Market. Another option to get information about Odds is to use the proper Include on any Fixtures related endpoint. Using the Include odds or flatodds will enrich the response of a Fixture with all Odds we have available.

Leagues and Seasons all over the world can have a different set up. The Stages endpoint can help you to define the current Stage or set up of multiple Stages of a particular League/Season.

Stage names are for example Regular Season, Play-offs, Semi-Finals, Final etc.

The Bookmakers endpoint will help you to set up Odds in a proper way in your website/application. This endpoint is very useful for administrative purposes to check and structure the Bookmakers' availability.

Bookmakers' data can be requested by ID or all in one response.

The Coaches endpoint provides you details about the Coach like the Name, Nationality Birthdate etc.

By default this endpoint returns Coach details that have managed at least one game in the Leagues covered by the Plan you are subscribed to.

GET News of all upcoming fixtures

We have news available for all upcoming English Premier League and Champions League matches as well as limited coverage for French Ligue 1, German Bundesliga, Italy Serie A and Spanish La Liga.

https://soccer.sportmonks.com/api/v2.0/news/fixtures/upcoming

Parameters

Include options

fixtures

Includes are the cornerstone of our API and allow you to enrich and customize your requests. This flexibility is what distinguishes us from our competitors.

You can learn more about what includes are and how they work here:

Example response

https://soccer.sportmonks.com/api/v2.0/news/fixtures?api_token={API_TOKE

Responses of the Seasons endpoint are limited to Seasons of the Leagues available in the Plan you are subscribed to. Responses provide you details like the Season ID, Name, League ID, Year and if the Season is Active Yes or No.

One of the main features of the Seasons endpoint is the ability to retrieve full Season Games, (history) Fixtures, Results or Upcoming Fixtures. This can be achieved by using the proper Includes, which are listed in the section Endpoint Details.

GET Venue by ID

https://soccer.sportmonks.com/api/v2.0/venues/{ID}

Parameters

No parameters available for this endpoint.

Include options

No includes available for this endpoint.

Example response

https://soccer.sportmonks.com/api/v2.0/venues/1?api_token={API_TOKEN}

"data": {
        "id": 1,
        "name": "Meadowbank Dorking",
        "surface": null,
        "address": null,
        "city": "Lviv",
        "capacity": 2000,
        "image_path": "https://cdn.sportmonks.com/images/soccer/venues/1/1.png",
        "coordinates": "51.234316,-0.33364"
    },

GET Coach by ID

https://soccer.sportmonks.com/api/v2.0/coaches/{ID}

Parameters

No parameters available for this endpoint.

Include options

No includes available for this endpoint.

Example response

https://soccer.sportmonks.com/api/v2.0/coaches/1467946?api_token={API_TOKEN}

"data": {
        "coach_id": 1467946,
        "team_id": 53,
        "country_id": 491,
        "common_name": "N. Lennon",
        "fullname": "Neil Lennon",
        "firstname": "Neil",
        "lastname": "Lennon",
        "nationality": "Northern Ireland",
        "birthdate": "25/06/1971",
        "birthcountry": "Northern Ireland",
        "birthplace": "Lurgan",
        "image_path": "https://cdn.sportmonks.com/images/soccer/players/10/1467946.png"
    },

Markets represent the betting options available per Bookmaker.

The Markets endpoint will help you to set up the Odds properly at your website/application. This endpoint is very useful for administrative purposes to check and structure the Markets availability.

Markets data can be requested by ID or all in one response.

GET Bookmaker by ID

https://soccer.sportmonks.com/api/v2.0/bookmakers/{ID}

Parameters

No parameters available for this endpoint.

Include options

No includes available for this endpoint.

Example response

https://soccer.sportmonks.com/api/v2.0/bookmakers/1?api_token={API_TOKEN}

    "data": {
        "id": 1,
        "name": "10Bet",
        "logo": null
    },

The TV Stations endpoint is about TV Stations broadcasting the Football Games. Per Fixture, the endpoint returns all TV Stations that broadcast the requested Game.

Since November 2017 we offer the ability to load historical Squads. This means you can retrieve Squads from 2005 onwards, including Player performance of the Games of the requested Season.

Welcome to Sportmonks’ Football API. We have designed the API for iGaming, media, developers and football enthusiasts. Sportmonks ensures that you can create a football application that meets your wishes and needs.

Football API 2.0 is a REST API that can be used to request football data from our wide-ranging database and has the following characteristics:

• Highly customizable requests

• Incredibly fast livescores

• Reliable and accurate data

You will find valuable tutorials and how-to guides to help you kickstart your application on these documentation pages. Let's get started right away by making your first request!

One of our newest features is the Prediction API. Predictions on markets like the Winner, Correct Scores, Over/Under and Both Teams To Score (BTTS) are all available here, produced with our Machine Learning techniques and models.

We offer endpoints to get the Probabilities per fixture or to Get all Probabilities. All probabilities are available 21 days before the match starts.

Sportmonks also detects Value Bets for you. The Value Bet API is processing thousands of historical odds data and market trends to find Value opportunities, compared to bookmakers' odds. Please note that not every match has Value Bets. Available endpoints are Value Bet by Fixture and Get all Value Bets.

GET Continent by ID

Parameters

Include options

countries

Includes are the cornerstone of our API and allow you to enrich and customize your requests. This flexibility is what distinguishes us from our competitors.

Example response

Use our Sportmonks Football News API to give an extra dimension to your application. Our News API has previews available for all upcoming English Premier League matches and EURO 2024.

GET Market by ID

Parameters

No parameters available for this endpoint.

Include options

No includes available for this endpoint.

Example response

GET All Continents

https://soccer.sportmonks.com/api/v2.0/continents

Parameters

Include options

countries

Includes are the cornerstone of our API and allow you to enrich and customize your requests. This flexibility is what distinguishes Sportmonks from our competitors.

You can learn more about what includes are and how they work here:

Example response

https://soccer.sportmonks.com/api/v2.0/continents?api_token={API_TOKEN}

"data": [
        {
            "id": 1,
            "name": "Europe"
        },
        {
            "id": 2,
            "name": "Asia"
        },
        {
            "id": 3,
            "name": "Africa"
        },
        {
            "id": 4,
            "name": "Oceania"
        },
        {
            "id": 5,
            "name": "Antarctica"
        },
        {
            "id": 6,
            "name": "North America"
        },
        {
            "id": 7,
            "name": "South America"
        }
    ]

GET Country by ID

Parameters

Include options

leagues continent covid

Includes are the cornerstone of our API and allow you to enrich and customize your requests. This flexibility is what distinguishes us from our competitors.

You can learn more about what includes are and how they work here:

Example response

GET Season by ID

Parameters

Include options

league stages rounds upcoming results groups goalscorers cardscorers assistscorers aggregatedGoalscorers aggregatedCardscorers aggregatedAssistscorers fixtures

Includes are the cornerstone of our API and allow you to enrich and customize your requests. This flexibility is what distinguishes us from our competitors.

You can learn more about what includes are and how they work here:

Example response

Get Video Highlights by Fixture ID

Parameters

No parameters available for this endpoint.

Include options

fixture

You can learn more about what includes are and how they work here:

Example response

GET Rounds by ID

Parameters

Include options

fixtures results season league

Includes are the cornerstone of our API and allow you to enrich and customize your requests. This flexibility is what distinguishes us from our competitors.

You can learn more about what includes are and how they work here:

Example response

Besides the Prediction API, we also have the Value Bet API. While the Prediction API evaluates the probabilities of game events, the Value Bet API is processing thousands of historical odds data and market trends to find Value opportunities, compared to bookmakers' odds.

Once the opening odds are available, the value detection algorithm is running every 10 minutes up to the beginning of the match. Each value detected by the model is coming with a set of features described below.

Please note that our algorithm detects Value Bets based on all available odds in combination with thefair_oddcalculated by the Value Bet algorithm. Therefore, not every match has a Value Bet available.

It is possible to use the endpoint as described on this page. It will give you all Value Bets detected. It is also possible to use the Value Bet By Fixture Id.

If you want to combine your Value Bets requests with your requests on the Fixture endpoint or Livescore endpoint, you can add the relationship include &include=valuebet. See the Relationship Fixture Value Bet for more info.

Get Value Bet by Fixture ID

Parameters

Include options

fixture

Includes are the cornerstone of our API and allow you to enrich and customize your requests. This flexibility is what distinguishes us from our competitors.

You can learn more about what includes are and how they work here:

Example response

GET TV Station by Fixture ID

Parameters

No parameters available for this endpoint.

Include options

No includes available for this endpoint.

Example response

Overview

1. What is Football API 2.0?

2. Authentication

3. Your first request

4. Get your football data

5. What can you do with the data?

6. Different plans and data features

What is Football API 2.0?

Build creative football-related apps with our Football API 2.0. Football API 2.0 is a REST API that can be used to request football data from our expansive database and has the following characteristics:

• Highly customizable requests

• Incredibly fast livescores

• Reliable and accurate data

Authentication

To make our first request, we’ll need a way to get authenticated first. Football API 2.0 utilizes API tokens for the authentication of requests. You can obtain your free API token and manage your API tokens Mysportmonks. For the sake of simplicity, we’ll be working with an API token within the ‘free plan’. The free plan includes the Danish Superliga (league id: 271) and the Scottish Premiership (league id: 501).

Example API token: [HdoiD312ND….]

The API token is only meant for your eyes and, as such, should be stored away safely.

Football API 2.0 utilizes response codes to indicate successful and failed API requests. With our brand-new token, we can make our first request! But before we start let us explain which possible responses can be returned. When making a request, a code response will always be returned. See below for a shortlist of possible code responses:

Your first request

Now that all prerequisites have been fulfilled, we’re ready to send our first request to the API!

Build the request

The request consists of the following components:

• The base URL

• A path parameter, in this example, we use [leagues]

• A query string parameter, this is optional, so we are leaving this out for now

• And finally, your API token

https://soccer.sportmonks.com/api/v2.0/

An example of a correctly authenticated request would be:

https://soccer.sportmonks.com/api/v2.0/leagues?api_token={API_TOKEN}

"data": [
        {
            "id": 271,
            "active": true,
            "type": "domestic",
            "legacy_id": 43,
            "country_id": 320,
            "logo_path": "https://cdn.sportmonks.com/images/soccer/leagues/271.png",
            "name": "Superliga",
            "is_cup": false,
            "current_season_id": 17328,
            "current_round_id": 199450,
            "current_stage_id": 77447994,
            "live_standings": true,
            "coverage": {
                "predictions": true,
                "topscorer_goals": true,
                "topscorer_assists": true,
                "topscorer_cards": true
            }

This request will return all of the leagues eligible for our free plan, which are the Danish Superliga (league id: 271) and the Scottish Premiership (league id: 501). You can view them by clicking on the second tab.

What can you do with the data?

The example above was the most basic request you can create, while our highly flexible football api 2.0 can handle way more advanced requests.

The data our API provides will enable you to create excellent and specialized applications. Down below you will find two examples of Sportmonks’ partners who have made brilliant applications. Throughout our documentation pages you will find more examples, ranging from betting and odds websites to fantasy games and live score tracking websites.

Code libraries

There are various options as to how you’d like to send the request. Our API is compatible with an incredible number of developer languages

• Node JS Wrapper: https://github.com/marchitos/sportmonks

• PHP Wrapper: https://github.com/joesaunderson/sportmonks-soccer

• Laravel PHP Wrapper: https://github.com/kirill-latish/laravel-sportmonks-soccer

• Composer PHP Wrapper: https://github.com/hristonev/sportmonks-client-bundle

• Phyton Wrappers:

  • https://github.com/tvl/python-sportmonk

  • https://github.com/Dmitrii-I/sportmonks

  • http://www.github.com/calestini/sportmonks_api

• Java Wrappers:

  • https://github.com/kevinsamyn/sportmonks-soccer

  • https://github.com/kete1987/sportmonks

• Ruby Wrappers:

  • https://github.com/valdemarua/sportmonks-ruby

  • https://github.com/vnnoder/sportmonks-ruby

• GO Wrapper: https://github.com/BialkowskiSz/go-sportmonks

• Elixir Wrapper: https://github.com/vnnoder/ex_sportmonks

• R Wrapper: https://github.com/systats/sportmonks

• Golang: https://github.com/statistico/statistico-sportmonks-go-client

Different plans and data features

Sportmonks has various different plans and data features for you. You can learn all about it in the matrix below. In Mysportmonks you can choose your ideal plan and data features.

GET Stage by ID

https://soccer.sportmonks.com/api/v2.0/stages/{ID}

Parameters

Include options

fixtures results season league

Includes are the cornerstone of our API and allow you to enrich and customize your requests. This flexibility is what distinguishes us from our competitors.

You can learn more about what includes are and how they work here:

Example response

https://soccer.sportmonks.com/api/v2.0/stages/77447500?api_token={API_TOKEN}

   "data": {
        "id": 77447500,
        "name": "2nd Phase",
        "type": "Group Stage",
        "league_id": 501,
        "season_id": 17141,
        "sort_order": 2,
        "has_standings": true
    },

GET Stage by ID

https://soccer.sportmonks.com/api/v2.0/stages/season/{ID}

Parameters

Include options

fixtures results season league

Includes are the cornerstone of our API and allow you to enrich and customize your requests. This flexibility is what distinguishes us from our competitors.

You can learn more about what includes are and how they work here:

Example response

https://soccer.sportmonks.com/api/v2.0/stages/season/17141?api_token={API_TOKEN}

  "data": [
        {
            "id": 77447500,
            "name": "2nd Phase",
            "type": "Group Stage",
            "league_id": 501,
            "season_id": 17141,
            "sort_order": 2,
            "has_standings": true
        },
        {
            "id": 77447501,
            "name": "1st Phase",
            "type": "Group Stage",
            "league_id": 501,
            "season_id": 17141,
            "sort_order": 1,
            "has_standings": true
        }
    ],

GET League by ID

Parameters

Include options

country season seasons

Includes are the cornerstone of our API and allow you to enrich and customize your requests. This flexibility is what distinguishes us from our competitors.

You can learn more about what includes are and how they work here:

Example response

GET News of all fixtures

We have news available for all upcoming English Premier League and Champions League matches as well as limited coverage for French Ligue 1, German Bundesliga, Italy Serie A and Spanish La Liga.

Parameters

Include options

fixtures

Includes are the cornerstone of our API and allow you to enrich and customize your requests. This flexibility is what distinguishes us from our competitors.

You can learn more about what includes are and how they work here:

Example response

Get Commentaries by Fixture ID

Parameters

No parameters available for this endpoint.

Include options

No includes available for this endpoint.

Example response

GET Team by ID

Parameters

Include options

country squad coach transfers sidelined stats venue fifaranking uefaranking visitorFixtures localFixtures visitorResults latest upcoming goalscorers cardscorers assistscorers aggregatedGoalscorers aggregatedCardscorers aggregatedAssistscorers league activeSeasons trophies rivals

Includes are the cornerstone of our API and allow you to enrich and customize your requests. This flexibility is what distinguishes us from our competitors.

You can learn more about what includes are and how they work here:

Example response

GET Standings Corrections by Season ID

Parameters

No parameters available for this endpoint.

Include options

No includes available for this endpoint.

Example response

GET Rivals by Team ID

Parameters

Include options

country squad coach transfers sidelined stats venue fifaranking uefaranking visitorFixtures localFixtures visitorResults latest upcoming goalscorers cardscorers assistscorers aggregatedGoalscorers aggregatedCardscorers aggregatedAssistscorers league activeSeasons trophies

Includes are the cornerstone of our API and allow you to enrich and customize your requests. This flexibility is what distinguishes us from our competitors.

You can learn more about what includes are and how they work here:

Example response

GET Inplay Odds by Fixture ID

Parameters

No parameters available for this endpoint.

Include options

No includes available for this endpoint.

Example response

GET All Bookmakers by Fixture ID

Parameters

No parameters available for this endpoint.

Include options

No includes available for this endpoint.

Example response

GET All Markets

Parameters

No parameters available for this endpoint.

Include options

No includes available for this endpoint.

Example response