Introduction
Welcome to the SportMonks API documentation. In this section of our website we hope to give you more insights in how our soccer and cricket API works so you can start implementing it in no time into your application.
Authentication
SportMonks uses API token to allow access to the API. You can register a new SportMonks API key here.
Got to https://www.sportmonks.com/settings#/api to create an API token
SportMonks expects the API token that can be included in all API requests to the server as part of the request
Continents
As the name of this endpoint already reveals, continents represent the part of the world to which countries belong to. Retrieving information about continents can be a very usefull feature to your app.
Make sure to replace d4ksomxFumF6veb..... with your API key.
Get All Continents
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/continents?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": [
{
"id": 1,
"name": "Europe"
},
{
"id": 2,
"name": "Asia"
}
]
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/continents?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
| include | false | This is the relationship that can be included. eg countries |
Response Attributes
| Name | Type | Description |
|---|---|---|
| id | integer | The id of the continent in the database |
| name | string | The name of the continent |
Get Continent By ID
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/continents/1?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": {
"id": 1,
"name": "Europe"
}
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/continents/{id}?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
| include | false | This is the relationship that can be included. eg countries |
Response Attributes
| Name | Type | Description |
|---|---|---|
| id | integer | The id of the continent in the database |
| name | string | The name of the continent |
Countries
Retrieving information about countries can be a very usefull feature to your app. Using the leagues include can be an easy way to list all leagues that are covered in your plan, that belong to the requested country.
Make sure to replace d4ksomxFumF6veb..... with your API key.
Get All Countries
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/countries?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": [
{
"id": 1,
"name": "Poland",
"extra": {
"continent": "Europe",
"sub_region": "Eastern Europe",
"world_region": "EMEA",
"fifa": "POL",
"iso": "POL",
"longitude": "19.37775993347168",
"latitude": "52.147850036621094",
"flag": "<svg xmlns='http://www.w3.org/2000/svg' width='1280' height='800' viewBox='0 0 16 10'><path fill='#fff' d='M0 0h16v10h-16z'/><path fill='#dc143c' d='M0 5h16v5h-16z'/></svg>"
}
},
{
"id": 2,
"name": "Brazil",
"extra": {
"continent": "Americas",
"sub_region": "South America",
"world_region": "AMER",
"fifa": "BRA",
"iso": "BRA",
"longitude": "-52.97311782836914",
"latitude": "-10.81045150756836",
"flag": "<svg version='1' xmlns='http://www.w3.org/2000/svg' width='720' height='504' viewBox='-2100 -1470 4200 2940'><path fill='#fff' d='M0 0h16v10h-16z'/><path fill='#dc143c' d='M0 5h16v5h-16z'/></svg>"
}
}
]
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/countries?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
| sort | false | This is the sorting attribute. If not provided, results will be sorted by id in ascending order. Options include id, name, code, updated_at, continent_id or active |
| include | false | This is the relationship that can be included. eg continent or leagues |
Response Attributes
| Name | Type | Description |
|---|---|---|
| id | integer | The id of the country in the database |
| name | string | The name of the country |
| continent | string | The continent in which this country belongs to |
| sub_region | string | The sub region in which this country belongs to |
| world_region | string | The world region in which this country belongs to |
| fifa | string | The fifa code of the country |
| iso | string | The iso code of the country |
| longitude | string | The longitude of the country |
| latitude | string | The latitude of the country |
| flag | string | The flag of the country |
Get Country By ID
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/countries/1?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": {
"id": 20,
"name": "Senegal",
"extra": {
"continent": "Africa",
"sub_region": "Western Africa",
"world_region": "EMEA",
"fifa": "SEN",
"iso": "SEN",
"longitude": "-14.531643867492676",
"latitude": "14.36251163482666",
"flag": "<svg version='1' xmlns='http://www.w3.org/2000/svg' width='00'height='00'viewBox=' 0 180 120'><path fill='#fff' d='M0 0h16v10h-16z'/><path fill='#dc143c' d='M0 5h16v5h-16z'/></svg>"
}
}
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/countries/{id}?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
| include | false | This is the relationship that can be included. eg continent or leagues |
| Name | Type | Description |
|---|---|---|
| id | integer | The id of the country in the database |
| name | string | The name of the country |
| continent | string | The continent in which this country belongs to |
| sub_region | string | The sub region in which this country belongs to |
| world_region | string | The world region in which this country belongs to |
| fifa | string | The fifa code of the country |
| iso | string | The iso code of the country |
| longitude | string | The longitude of the country |
| latitude | string | The latitude of the country |
| flag | string | The flag of the country |
Leagues
The response of this endpoint is limited to the leagues that are assigned to your subscription. So, if you request the /leagues endpoint this will return all the leagues you have access to. For most applications leagues is the starting point. You can retrieve all seasons we cover via seasons include or just the active season via season include.
Make sure to replace d4ksomxFumF6veb..... with your API key.
Get All Leagues
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/leagues?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": [
{
"id": 1,
"legacy_id": 4,
"country_id": 13,
"name": "Superliga",
"is_cup": false,
"current_season_id": 1,
"current_round_id": 1,
"current_stage_id": 7,
"live_standings": true,
"coverage": {
"topscorer_goals": true,
"topscorer_assists": true,
"topscorer_cards": true
}
},
{
"id": 2,
"legacy_id": 6,
"country_id": 11,
"name": "Premiership",
"is_cup": false,
"current_season_id": 1,
"current_round_id": 1,
"current_stage_id": 7,
"live_standings": true,
"coverage": {
"topscorer_goals": true,
"topscorer_assists": true,
"topscorer_cards": true
}
}
]
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/leagues?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
| include | false | This is the relationship that can be included. eg country, season (current season) or seasons |
Response Attributes
| Name | Type | Description |
|---|---|---|
| id | integer | The id of the league in the database |
| name | string | The name of the league |
| legacy_id | integer | The legacy id of the league |
| country_id | integer | The legacy id of the league |
| is_cup | boolean | Is it a cup league |
| current_season_id | integer | The id of the current season |
| current_round_id | integer | The id of the current round |
| current_stage_id | integer | The id of the current stage |
| live_standings | boolean | Are there live standings? |
| coverage | object | These include topscorer_goals, topscorer_assists and topscorer_cards |
Get League By ID
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/leagues/1?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": {
"id": 2,
"legacy_id": 6,
"country_id": 11,
"name": "Premiership",
"is_cup": false,
"current_season_id": 1,
"current_round_id": 1,
"current_stage_id": 7,
"live_standings": true,
"coverage": {
"topscorer_goals": true,
"topscorer_assists": true,
"topscorer_cards": true
}
}
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/leagues/{id}?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
| include | false | This is the relationship that can be included. eg country, season (current season) or seasons |
Response Attributes
| Name | Type | Description |
|---|---|---|
| id | integer | The id of the league in the database |
| name | string | The name of the league |
| legacy_id | integer | The legacy id of the league |
| country_id | integer | The legacy id of the league |
| is_cup | boolean | Is it a cup league |
| current_season_id | integer | The id of the current season |
| current_round_id | integer | The id of the current round |
| current_stage_id | integer | The id of the current stage |
| live_standings | boolean | Are there live standings? |
| coverage | object | These include topscorer_goals, topscorer_assists and topscorer_cards |
Seasons
The response of this endpoint is limited to the leaguess that are assigned to your subscription. Via this endpoint you can retrieve details about a particular season. For example you can find out if a season is still active. Another great feature, when using the proper includes, is the ability to load full season games, or just only results or upcoming fixtures.
Make sure to replace d4ksomxFumF6veb..... with your API key.
Get All Seasons
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/seasons?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": [
{
"id": 1,
"name": "2015/2016",
"league_id": 2,
"is_current_season": false,
"current_round_id": 1,
"current_stage_id": 7
},
{
"id": 3,
"name": "2014/2015",
"league_id": 2,
"is_current_season": false,
"current_round_id": 7,
"current_stage_id": 8
}
]
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/seasons?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
| include | false | This is the relationship that can be included. eg leagues, stages, rounds, fixtures, upcoming, results, groups |
Response Attributes
| Name | Type | Description |
|---|---|---|
| id | integer | The id of the season in the database |
| name | string | The name of the season |
| league_id | integer | The id of the league associated with this season |
| is_current_season | boolean | Is this the current season? |
| current_stage_id | integer | The id of the current stage |
| current_round_id | integer | The id of the current round |
Get Season By ID
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/seasons/1?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": {
"id": 1,
"name": "2015/2016",
"league_id": 21,
"is_current_season": false,
"current_round_id": 1,
"current_stage_id": 7
}
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/seasons/{id}?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
| include | false | This is the relationship that can be included. eg leagues, stages, rounds, fixtures, upcoming, results, groups |
Response Attributes
| Name | Type | Description |
|---|---|---|
| id | integer | The id of the season in the database |
| name | string | The name of the season |
| league_id | integer | The id of the league associated with this season |
| is_current_season | boolean | Is this the current season? |
| current_stage_id | integer | The id of the current stage |
| current_round_id | integer | The id of the current round |
Fixtures
The response of this endpoint is limited to the leagues that are assigned to your subscription. Fixtures represent a game played in a particular league. A Fixture is played between 2 teams. Without using includes this will return information about the current status of 1 or more games. You can enrich the the game by adding the proper includes.
Make sure to replace d4ksomxFumF6veb..... with your API key.
Get Fixture By ID
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/fixtures/1?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": {
"id": 1,
"league_id": 2,
"season_id": 4,
"stage_id": 1,
"round_id": 14,
"group_id": 9,
"aggregate_id": 8,
"venue_id": 29,
"referee_id": 18,
"localteam_id": 39,
"visitorteam_id": 38,
"weather_report": null,
"commentaries": false,
"attendance": null,
"pitch": null,
"winning_odds_calculated": false,
"formations": {
"localteam_formation": null,
"visitorteam_formation": null
},
"scores": {
"localteam_score": 0,
"visitorteam_score": 0,
"localteam_pen_score": 0,
"visitorteam_pen_score": 0,
"ht_score": null,
"ft_score": null,
"et_score": null
},
"time": {
"status": "NS",
"starting_at": {
"date_time": "2018-11-23 18:00:00",
"date": "2018-11-23",
"time": "18:00:00",
"timestamp": "1542996000",
"timezone": "UTC"
},
"minute": null,
"second": null,
"added_time": null,
"extra_minute": null,
"injury_time": null
},
"coaches": {
"localteam_coach_id": null,
"visitorteam_coach_id": null
},
"standings": {
"localteam_position": 13,
"visitorteam_position": 7
},
"leg": "1/1",
"colors": null,
"deleted": false
}
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/fixtures/{id}?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
| include | false | This is the relationship that can be included. eg localTeam, visitorTeam, substitutions, goals, cards, other, corners, lineup, bench, sidelined, stats, comments, tvstations, highlights, league, season, round, stage, referee, events, venue, odds, flatOdds, inplay, localCoach, visitorCoach, group, trends |
Response Attributes
| Name | Type | Description |
|---|---|---|
| id | integer | The id of the fixture in the database |
| league_id | integer | The id of the league associated with this fixture |
| season_id | integer | The id of the season associated with this fixture |
| stage_id | integer | The id of the stage associated with this fixture |
| round_id | string | round id of the fixture |
| group_id | integer | The id of the group associated with this fixture |
| aggregate_id | integer | The id of the aggregate associated with this fixture |
| venue_id | integer | The id of the venue for this fixture |
| referee_id | integer | The id of the referee for this fixture |
| localteam_id | integer | Id of the team playing at home |
| visitorteam_id | integer | Id of the team played away |
| weather_report | object | Report of the weather. Includes: temperature, clouds, humidity, wind, clouds |
| commentaries | boolean | Are there commentaries? |
| attendance | string | the attendance of the match |
| pitch | string | the name of the pitch |
| winning_odds_calculated | boolean | are winning odds calculated? |
| formations | object | an object containing local team formations and visitor team formations |
| scores | object | an object containing the score breakdown |
| time | object | an object containing details about time |
| coaches | object | an object containing details of local coach and visiting coach |
| standings | object | an object containing local team position and visitor team position |
| colors | object | the colors of the teams |
Get Fixture Between 2 Dates
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/fixtures/between/2018-01-01/2018-12-01?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": [
{
"id": 1,
"league_id": 2,
"season_id": 4,
"stage_id": 1,
"round_id": 14,
"group_id": 9,
"aggregate_id": 8,
"venue_id": 29,
"referee_id": 18,
"localteam_id": 39,
"visitorteam_id": 38,
"weather_report": {
"code": "clouds",
"type": "broken clouds",
"icon": "https://cdn.sportmonks.com/images/weather/04n.png",
"temperature": {
"temp": 43.97,
"unit": "fahrenheit"
},
"clouds": "75%",
"humidity": "81%",
"wind": {
"speed": "13.87 m/s",
"degree": 230
}
},
"commentaries": true,
"attendance": null,
"pitch": "Good",
"winning_odds_calculated": true,
"formations": {
"localteam_formation": "4-2-3-1",
"visitorteam_formation": "4-2-3-1"
},
"scores": {
"localteam_score": 1,
"visitorteam_score": 2,
"localteam_pen_score": 0,
"visitorteam_pen_score": 0,
"ht_score": "1-0",
"ft_score": "1-2",
"et_score": null
},
"time": {
"status": "FT",
"starting_at": {
"date_time": "2018-11-23 18:00:00",
"date": "2018-11-23",
"time": "18:00:00",
"timestamp": "1542996000",
"timezone": "UTC"
},
"minute": 90,
"second": null,
"added_time": null,
"extra_minute": null,
"injury_time": null
},
"coaches": {
"localteam_coach_id": 80,
"visitorteam_coach_id": 23
},
"standings": {
"localteam_position": 11,
"visitorteam_position": 1
},
"leg": null,
"colors": null,
"deleted": false
},
{
"id": 5,
"league_id": 12,
"season_id": 34,
"stage_id": 13,
"round_id": 4,
"..."
"weather_report": {
"code": "snow",
"type": "shower sleet",
"icon": "https://cdn.sportmonks.com/images/weather/04n.png",
"temperature": {
"temp": 37.23,
"unit": "fahrenheit"
},
"clouds": "48%",
"humidity": "74%",
"wind": {
"speed": "12.75 m/s",
"degree": 270
}
},
"..."
"time": {
"status": "FT",
"starting_at": {
"date_time": "2018-10-13 15:00:00",
"date": "2018-10-13",
"time": "18:00:00",
"timestamp": "1542346000",
"timezone": "UTC"
},
"minute": 90,
"second": null,
"added_time": 0,
"extra_minute": null,
"injury_time": 4
},
}
]
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/fixtures/between/{from}/{to}?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
| include | false | This is the relationship that can be included. eg localTeam, visitorTeam, substitutions, goals, cards, other, corners, lineup, bench, sidelined, stats, comments, tvstations, highlights, league, season, round, stage, referee, events, venue, odds, flatOdds, inplay, localCoach, visitorCoach, group, trends |
Response Attributes
| Name | Type | Description |
|---|---|---|
| id | integer | The id of the fixture in the database |
| league_id | integer | The id of the league associated with this fixture |
| season_id | integer | The id of the season associated with this fixture |
| stage_id | integer | The id of the stage associated with this fixture |
| round_id | string | round id of the fixture |
| group_id | integer | The id of the group associated with this fixture |
| aggregate_id | integer | The id of the aggregate associated with this fixture |
| venue_id | integer | The id of the venue for this fixture |
| referee_id | integer | The id of the referee for this fixture |
| localteam_id | integer | Id of the team playing at home |
| visitorteam_id | integer | Id of the team played away |
| weather_report | object | Report of the weather. Includes: temperature, clouds, humidity, wind, clouds |
| commentaries | boolean | Are there commentaries? |
| attendance | string | the attendance of the match |
| pitch | string | the name of the pitch |
| winning_odds_calculated | boolean | are winning odds calculated? |
| formations | object | an object containing local team formations and visitor team formations |
| scores | object | an object containing the score breakdown |
| time | object | an object containing details about time |
| coaches | object | an object containing details of local coach and visiting coach |
| standings | object | an object containing local team position and visitor team position |
| colors | object | the colors of the teams |
Get Fixture Between 2 Dates For a Team
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/fixtures/between/2018-01-01/2018-12-01/1?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": [
{
"id": 1,
"league_id": 2,
"season_id": 4,
"stage_id": 1,
"round_id": 14,
"group_id": 9,
"aggregate_id": 8,
"venue_id": 29,
"referee_id": 18,
"localteam_id": 39,
"visitorteam_id": 38,
"weather_report": {
"code": "snow",
"type": "shower sleet",
"icon": "https://cdn.sportmonks.com/images/weather/04n.png",
"temperature": {
"temp": 37.23,
"unit": "fahrenheit"
},
"clouds": "48%",
"humidity": "74%",
"wind": {
"speed": "12.75 m/s",
"degree": 270
}
},
"commentaries": true,
"attendance": null,
"pitch": "Good",
"winning_odds_calculated": true,
"formations": {
"localteam_formation": "4-4-2",
"visitorteam_formation": "4-4-2"
},
"scores": {
"localteam_score": 1,
"visitorteam_score": 2,
"localteam_pen_score": 0,
"visitorteam_pen_score": 0,
"ht_score": "1-0",
"ft_score": "1-2",
"et_score": null
},
"time": {
"status": "FT",
"starting_at": {
"date_time": "2018-11-23 18:00:00",
"date": "2018-11-23",
"time": "18:00:00",
"timestamp": "1542996000",
"timezone": "UTC"
},
"minute": 90,
"second": null,
"added_time": null,
"extra_minute": null,
"injury_time": null
},
"coaches": {
"localteam_coach_id": 80,
"visitorteam_coach_id": 23
},
"standings": {
"localteam_position": 11,
"visitorteam_position": 1
},
"leg": null,
"colors": null,
"deleted": false
},
{
"id": 5,
"league_id": 12,
"season_id": 34,
"stage_id": 13,
"round_id": 4,
"..."
"weather_report": {
"code": "snow",
"type": "shower sleet",
"icon": "https://cdn.sportmonks.com/images/weather/04n.png",
"temperature": {
"temp": 37.23,
"unit": "fahrenheit"
},
"clouds": "48%",
"humidity": "74%",
"wind": {
"speed": "12.75 m/s",
"degree": 270
}
},
"..."
"time": {
"status": "FT",
"starting_at": {
"date_time": "2018-10-13 15:00:00",
"date": "2018-10-13",
"time": "18:00:00",
"timestamp": "1542346000",
"timezone": "UTC"
},
"minute": 90,
"second": null,
"added_time": 0,
"extra_minute": null,
"injury_time": 4
},
}
]
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/fixtures/between/{from}/{to}/{team_id}?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
| include | false | This is the relationship that can be included. eg localTeam, visitorTeam, substitutions, goals, cards, other, corners, lineup, bench, sidelined, stats, comments, tvstations, highlights, league, season, round, stage, referee, events, venue, odds, flatOdds, inplay, localCoach, visitorCoach, group, trends |
Response Attributes
| Name | Type | Description |
|---|---|---|
| id | integer | The id of the fixture in the database |
| league_id | integer | The id of the league associated with this fixture |
| season_id | integer | The id of the season associated with this fixture |
| stage_id | integer | The id of the stage associated with this fixture |
| round_id | string | round id of the fixture |
| group_id | integer | The id of the group associated with this fixture |
| aggregate_id | integer | The id of the aggregate associated with this fixture |
| venue_id | integer | The id of the venue for this fixture |
| referee_id | integer | The id of the referee for this fixture |
| localteam_id | integer | Id of the team playing at home |
| visitorteam_id | integer | Id of the team played away |
| weather_report | object | Report of the weather. Includes: temperature, clouds, humidity, wind, clouds |
| commentaries | boolean | Are there commentaries? |
| attendance | string | the attendance of the match |
| pitch | string | the name of the pitch |
| winning_odds_calculated | boolean | are winning odds calculated? |
| formations | object | an object containing local team formations and visitor team formations |
| scores | object | an object containing the score breakdown |
| time | object | an object containing details about time |
| coaches | object | an object containing details of local coach and visiting coach |
| standings | object | an object containing local team position and visitor team position |
| colors | object | the colors of the teams |
Get Fixture For a Specific Date
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/fixtures/date/2018-11-23?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": [
{
"id": 1,
"league_id": 22,
"season_id": 14,
"stage_id": 51,
"round_id": 114,
"group_id": 29,
"aggregate_id": 18,
"venue_id": 29,
"referee_id": 8,
"localteam_id": 9,
"visitorteam_id": 8,
"weather_report": null,
"commentaries": null,
"attendance": 4024,
"pitch": null,
"winning_odds_calculated": true,
"formations": {
"localteam_formation": "4-4-2",
"visitorteam_formation": "3-5-2"
},
"scores": {
"localteam_score": 1,
"visitorteam_score": 0,
"localteam_pen_score": 0,
"visitorteam_pen_score": 0,
"ht_score": "1-0",
"ft_score": "1-0",
"et_score": null
},
"time": {
"status": "FT",
"starting_at": {
"date_time": "2018-11-23 18:00:00",
"date": "2018-11-23",
"time": "18:00:00",
"timestamp": "1542996000",
"timezone": "UTC"
},
"minute": 90,
"second": null,
"added_time": 0,
"extra_minute": null,
"injury_time": 4
},
"coaches": {
"localteam_coach_id": 80,
"visitorteam_coach_id": 23
},
"standings": {
"localteam_position": 14,
"visitorteam_position": 12
},
"leg": null,
"colors": {
"localteam": {
"color": null,
"kit_colors": null
},
"visitorteam": {
"color": null,
"kit_colors": null
}
},
"deleted": false
},
{
"id": 2,
"league_id": 22,
"season_id": 14,
"stage_id": 51,
"round_id": 114,
"..."
"time": {
"status": "FT",
"starting_at": {
"date_time": "2018-11-23 15:00:00",
"date": "2018-11-23",
"time": "18:00:00",
"timestamp": "1542346000",
"timezone": "UTC"
},
"minute": 90,
"second": null,
"added_time": 0,
"extra_minute": null,
"injury_time": null
},
"..."
"leg": null,
"colors": null,
"deleted": false
}
]
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/fixtures/date/{date}?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
| include | false | This is the relationship that can be included. eg localTeam, visitorTeam, substitutions, goals, cards, other, corners, lineup, bench, sidelined, stats, comments, tvstations, highlights, league, season, round, stage, referee, events, venue, odds, flatOdds, inplay, localCoach, visitorCoach, group, trends |
Response Attributes
| Name | Type | Description |
|---|---|---|
| id | integer | The id of the fixture in the database |
| league_id | integer | The id of the league associated with this fixture |
| season_id | integer | The id of the season associated with this fixture |
| stage_id | integer | The id of the stage associated with this fixture |
| round_id | string | round id of the fixture |
| group_id | integer | The id of the group associated with this fixture |
| aggregate_id | integer | The id of the aggregate associated with this fixture |
| venue_id | integer | The id of the venue for this fixture |
| referee_id | integer | The id of the referee for this fixture |
| localteam_id | integer | Id of the team playing at home |
| visitorteam_id | integer | Id of the team played away |
| weather_report | object | Report of the weather. Includes: temperature, clouds, humidity, wind, clouds |
| commentaries | boolean | Are there commentaries? |
| attendance | string | the attendance of the match |
| pitch | string | the name of the pitch |
| winning_odds_calculated | boolean | are winning odds calculated? |
| formations | object | an object containing local team formations and visitor team formations |
| scores | object | an object containing the score breakdown |
| time | object | an object containing details about time |
| coaches | object | an object containing details of local coach and visiting coach |
| standings | object | an object containing local team position and visitor team position |
| colors | object | the colors of the teams |
Get Multiple Fixtures by Id
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/fixtures/multi/1,2?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": [
{
"id": 1,
"league_id": 2,
"season_id": 4,
"stage_id": 1,
"round_id": 14,
"group_id": 9,
"aggregate_id": 8,
"venue_id": 29,
"referee_id": 18,
"localteam_id": 39,
"visitorteam_id": 38,
"weather_report": {
"code": "clouds",
"type": "broken clouds",
"icon": "https://cdn.sportmonks.com/images/weather/04n.png",
"temperature": {
"temp": 43.97,
"unit": "fahrenheit"
},
"clouds": "75%",
"humidity": "81%",
"wind": {
"speed": "13.87 m/s",
"degree": 230
}
},
"commentaries": true,
"attendance": null,
"pitch": "Good",
"winning_odds_calculated": true,
"formations": {
"localteam_formation": "4-2-3-1",
"visitorteam_formation": "4-2-3-1"
},
"scores": {
"localteam_score": 1,
"visitorteam_score": 2,
"localteam_pen_score": 0,
"visitorteam_pen_score": 0,
"ht_score": "1-0",
"ft_score": "1-2",
"et_score": null
},
"time": {
"status": "FT",
"starting_at": {
"date_time": "2018-11-23 18:00:00",
"date": "2018-11-23",
"time": "18:00:00",
"timestamp": "1542996000",
"timezone": "UTC"
},
"minute": 90,
"second": null,
"added_time": null,
"extra_minute": null,
"injury_time": null
},
"coaches": {
"localteam_coach_id": 80,
"visitorteam_coach_id": 23
},
"standings": {
"localteam_position": 11,
"visitorteam_position": 1
},
"leg": null,
"colors": null,
"deleted": false
},
{
"id": 2,
"league_id": 2,
"season_id": 4,
"..."
"leg": null,
"colors": null,
"deleted": false
}
]
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/fixtures/multi/{id_list}?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
| include | false | This is the relationship that can be included. eg localTeam, visitorTeam, substitutions, goals, cards, other, corners, lineup, bench, sidelined, stats, comments, tvstations, highlights, league, season, round, stage, referee, events, venue, odds, flatOdds, inplay, localCoach, visitorCoach, group, trends |
Response Attributes
| Name | Type | Description |
|---|---|---|
| id | integer | The id of the fixture in the database |
| league_id | integer | The id of the league associated with this fixture |
| season_id | integer | The id of the season associated with this fixture |
| stage_id | integer | The id of the stage associated with this fixture |
| round_id | string | round id of the fixture |
| group_id | integer | The id of the group associated with this fixture |
| aggregate_id | integer | The id of the aggregate associated with this fixture |
| venue_id | integer | The id of the venue for this fixture |
| referee_id | integer | The id of the referee for this fixture |
| localteam_id | integer | Id of the team playing at home |
| visitorteam_id | integer | Id of the team played away |
| weather_report | object | Report of the weather. Includes: temperature, clouds, humidity, wind, clouds |
| commentaries | boolean | Are there commentaries? |
| attendance | string | the attendance of the match |
| pitch | string | the name of the pitch |
| winning_odds_calculated | boolean | are winning odds calculated? |
| formations | object | an object containing local team formations and visitor team formations |
| scores | object | an object containing the score breakdown |
| time | object | an object containing details about time |
| coaches | object | an object containing details of local coach and visiting coach |
| standings | object | an object containing local team position and visitor team position |
| colors | object | the colors of the teams |
Livescores
This endpoint returns all live fixtures covered by the subscription of the user. Via these endpoints you are able to obtain live information for games of the current day. Information provided by these endpoints are never cached and are real-time.
Make sure to replace d4ksomxFumF6veb..... with your API key.
Get All Livescores
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/livescores?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": [
{
"id": 1,
"league_id": 2,
"season_id": 4,
"stage_id": 1,
"round_id": 14,
"group_id": 9,
"aggregate_id": 8,
"venue_id": 29,
"referee_id": 18,
"localteam_id": 39,
"visitorteam_id": 38,
"weather_report": null,
"commentaries": false,
"attendance": null,
"pitch": null,
"winning_odds_calculated": false,
"formations": {
"localteam_formation": null,
"visitorteam_formation": null
},
"scores": {
"localteam_score": 0,
"visitorteam_score": 0,
"localteam_pen_score": 0,
"visitorteam_pen_score": 0,
"ht_score": null,
"ft_score": null,
"et_score": null
},
"time": {
"status": "NS",
"starting_at": {
"date_time": "2018-11-23 18:00:00",
"date": "2018-11-23",
"time": "18:00:00",
"timestamp": "1542996000",
"timezone": "UTC"
},
"minute": null,
"second": null,
"added_time": null,
"extra_minute": null,
"injury_time": null
},
"coaches": {
"localteam_coach_id": null,
"visitorteam_coach_id": null
},
"standings": {
"localteam_position": 13,
"visitorteam_position": 7
},
"leg": "1/1",
"colors": null,
"deleted": false
}
]
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/livescores?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
| include | false | This is the relationship that can be included. eg localTeam, visitorTeam, substitutions, goals, cards, other, corners, lineup, bench, sidelined, stats, comments, tvstations, highlights, league, season, round, stage, referee, events, venue, odds, flatOdds, inplay, localCoach, visitorCoach, group, trends |
Response Attributes
| Name | Type | Description |
|---|---|---|
| id | integer | The id of the livescore in the database |
| league_id | integer | The id of the league associated with this livescore |
| season_id | integer | The id of the season associated with this livescore |
| stage_id | integer | The id of the stage associated with this livescore |
| round_id | string | round id of the livescore |
| group_id | integer | The id of the group associated with this livescore |
| aggregate_id | integer | The id of the aggregate associated with this livescore |
| venue_id | integer | The id of the venue for this livescore |
| referee_id | integer | The id of the referee for this livescore |
| localteam_id | integer | Id of the team playing at home |
| visitorteam_id | integer | Id of the team played away |
| weather_report | object | Report of the weather. Includes: temperature, clouds, humidity, wind, clouds |
| commentaries | boolean | Are there commentaries? |
| attendance | string | the attendance of the match |
| pitch | string | the name of the pitch |
| winning_odds_calculated | boolean | are winning odds calculated? |
| formations | object | an object containing local team formations and visitor team formations |
| scores | object | an object containing the score breakdown |
| time | object | an object containing details about time |
| coaches | object | an object containing details of local coach and visiting coach |
| standings | object | an object containing local team position and visitor team position |
| colors | object | the colors of the teams |
Get Livescore In-play
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/livescores/now?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": {
"id": 1,
"league_id": 2,
"season_id": 4,
"stage_id": 1,
"round_id": 14,
"group_id": 9,
"aggregate_id": 8,
"venue_id": 29,
"referee_id": 18,
"localteam_id": 39,
"visitorteam_id": 38,
"weather_report": null,
"commentaries": false,
"attendance": null,
"pitch": null,
"winning_odds_calculated": false,
"formations": {
"localteam_formation": null,
"visitorteam_formation": null
},
"scores": {
"localteam_score": 0,
"visitorteam_score": 0,
"localteam_pen_score": 0,
"visitorteam_pen_score": 0,
"ht_score": null,
"ft_score": null,
"et_score": null
},
"time": {
"status": "NS",
"starting_at": {
"date_time": "2018-11-23 18:00:00",
"date": "2018-11-23",
"time": "18:00:00",
"timestamp": "1542996000",
"timezone": "UTC"
},
"minute": null,
"second": null,
"added_time": null,
"extra_minute": null,
"injury_time": null
},
"coaches": {
"localteam_coach_id": null,
"visitorteam_coach_id": null
},
"standings": {
"localteam_position": 13,
"visitorteam_position": 7
},
"leg": "1/1",
"colors": null,
"deleted": false
}
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/livescores/now?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
| include | false | This is the relationship that can be included. eg localTeam, visitorTeam, substitutions, goals, cards, other, corners, lineup, bench, sidelined, stats, comments, tvstations, highlights, league, season, round, stage, referee, events, venue, odds, flatOdds, inplay, localCoach, visitorCoach, group, trends |
Response Attributes
| Name | Type | Description |
|---|---|---|
| id | integer | The id of the livescore in the database |
| league_id | integer | The id of the league associated with this livescore |
| season_id | integer | The id of the season associated with this livescore |
| stage_id | integer | The id of the stage associated with this livescore |
| round_id | string | round id of the livescore |
| group_id | integer | The id of the group associated with this livescore |
| aggregate_id | integer | The id of the aggregate associated with this livescore |
| venue_id | integer | The id of the venue for this livescore |
| referee_id | integer | The id of the referee for this livescore |
| localteam_id | integer | Id of the team playing at home |
| visitorteam_id | integer | Id of the team played away |
| weather_report | array | report of the weather |
| commentaries | boolean | Are there commentaries? |
| attendance | string | the attendance of the match |
| pitch | string | the name of the pitch |
| winning_odds_calculated | boolean | are winning odds calculated? |
| formations | object | an object containing local team formations and visitor team formations |
| scores | object | an object containing the score breakdown |
| time | object | an object containing details about time |
| coaches | object | an object containing details of local coach and visiting coach |
| standings | object | an object containing local team position and visitor team position |
| colors | object | the colors of the teams |
Teams
If you need details about a team than this is the API to use. In it's pure form it will get you information about when the team started, what the address of their stadium is etc. When using the proper includes you can also get the status of the current season, the venue they play in, their current squad & coach etc.
Please note that the squad include only return the squad for the teams of the active season in the domestic main league the team is playing in. For international teams it will return the teams as is.
Please note that the following includes only returns the last or upcoming 25 items. visitorFixtures, localFixtures, visitorResults, localResults, latest, upcoming
The latest, upcoming and fixtures include may cause the response to be very big and finally fail because of memory limitations. To prevent this from happening we would suggest you to use filters to only return the data you actually need. an example could be: &include=localTeam.upcoming:limit(5|1):order(starting_at|asc)
Please note that the fifarankings include is currently only available for national teams.
Make sure to replace d4ksomxFumF6veb..... with your API key.
Get Team by Season
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/teams/season/1?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": [
{
"id": 1,
"legacy_id": 14,
"name": "København",
"short_code": "COP",
"twitter": null,
"country_id": 12,
"national_team": false,
"founded": 1992,
"logo_path": "https://cdn.sportmonks.com/images/path/to/team1.png",
"venue_id": 5
},
{
"id": 2,
"legacy_id": 4,
"name": "Midtjylland",
"short_code": "FCM",
"twitter": null,
"country_id": 32,
"national_team": false,
"founded": 1999,
"logo_path": "https://cdn.sportmonks.com/images/path/to/team2.png",
"venue_id": 7
}
]
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/teams/season/{id}?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
| include | false | This is the relationship that can be included. eg country, squad*, coach, transfers, sidelined, stats, venue, fifaranking, uefaranking, visitorFixtures, localFixtures, visitorResults, localResults, latest or upcoming |
Response Attributes
| Name | Type | Description |
|---|---|---|
| id | integer | The id of the team in the database |
| legacy_id | integer | The legacy id of the team |
| name | string | The name of the team |
| short_code | string | The short code used to represent the team |
| logo_path | integer | Path to the team's image |
| national_team | boolean | This ia a boolean to show whether the team is a national team or not |
| string | The twitter handle of the team | |
| country_id | integer | The id of the country in which this team belongs to |
| founded | integer | The year when this team was founded |
| venue_id | integer | The venue where this team plays |
Get Team By ID
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/teams/1?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": {
"id": 1,
"legacy_id": 14,
"name": "København",
"short_code": "COP",
"twitter": null,
"country_id": 12,
"national_team": false,
"founded": 1992,
"logo_path": "https://cdn.sportmonks.com/images/path/to/team1.png",
"venue_id": 5
}
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/teams/{id}?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
| include | false | This is the relationship that can be included. eg country, squad*, coach, transfers, sidelined, stats, venue, fifaranking, uefaranking, visitorFixtures, localFixtures, visitorResults, localResults, latest or upcoming |
Response Attributes
| Name | Type | Description |
|---|---|---|
| id | integer | The id of the team in the database |
| legacy_id | integer | The legacy id of the team |
| name | string | The name of the team |
| short_code | string | The short code used to represent the team |
| logo_path | integer | Path to the team's image |
| national_team | boolean | This ia a boolean to show whether the team is a national team or not |
| string | The twitter handle of the team | |
| country_id | integer | The id of the country in which this team belongs to |
| founded | integer | The year when this team was founded |
| venue_id | integer | The venue where this team plays |
Players
With this endpoint you are able to build a complete player profile. You can include it's stats to see the progression of the player over the current domestic season. You can also use includes to get data about his previous progression as well.
Make sure to replace d4ksomxFumF6veb..... with your API key.
Get Player By ID
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/players/1?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": {
"player_id": 1,
"team_id": 2,
"country_id": 2,
"position_id": 2,
"common_name": "P. Jagielka",
"fullname": "P. Jagielka",
"firstname": "Phil",
"lastname": "Jagielka",
"nationality": "England",
"birthdate": "17/08/1982",
"birthcountry": "England",
"birthplace": "Sale",
"height": "180 cm",
"weight": "87 kg",
"image_path": "https://cdn.sportmonks.com/images/path/to/player1.png",
}
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/players/{id}?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
| include | false | This is the relationship that can be included. eg position team, stats, trophies.seasons, sidelined or transfers |
Response Attributes
| Name | Type | Description |
|---|---|---|
| player_id | integer | The id of the player in the database |
| position_id | integer | The position id of the player |
| country_id | integer | The country id of the player |
| team_id | integer | The team id of the player |
| firstname | string | The first name of the player |
| lastname | string | The last name of the player |
| fullname | string | The full name of the player |
| common_name | string | The common name that this player goes by |
| nationality | string | The nationality of the player |
| image_path | string | Path to the image of the player |
| birthdate | string | The date of birth of the player |
| birtcountry | string | The country where the player was born |
| birthplace | string | The place where the player was born |
| height | string | The height of the player |
| weight | string | The weight of the player |
Coaches
By default this endpoint returns coach details that have hosted at least 1 game under the leagues covered by the subscription of the user.
Make sure to replace d4ksomxFumF6veb..... with your API key.
Get Coach By ID
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/coach/1?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": {
"coach_id": 1,
"team_id": 3,
"country_id": 14,
"common_name": "A. Kuhn",
"fullname": "A. Kuhn",
"firstname": "Allan",
"lastname": "Kuhn",
"nationality": "Denmark",
"image_path": "https://cdn.sportmonks.com/images/path/to/official1.png",
"birthdate": "02/03/1968",
"birthcountry": "Denmark",
"birthplace": null
}
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/coach/{id}?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
Response Attributes
| Name | Type | Description |
|---|---|---|
| id | integer | The id of the coach in the database |
| firstname | string | The first name of the coach |
| lastname | string | The last name of the coach |
| fullname | string | The full name of the coach |
| common_name | string | The common name of the coach |
| nationality | string | The nationality of the coach |
| image_path | integer | Path to the image of the coach |
| birthdate | integer | The date of birth of the coach |
| country_id | integer | The country id of the coach |
| team_id | integer | The team id of the coach |
| birtcountry | string | The country where the coach was born |
| birthplace | string | The place where the coach was born |
Venues
With this endpoint you have the ability to retrieve details like, pitch type, address, capacity of a given venue. Besides data we also offer a picture of the venue for most of them.
Make sure to replace d4ksomxFumF6veb..... with your API key.
Get Venue By ID
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/venues/1?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": {
"id": 1,
"name": "Central Coast Stadium",
"city": "Gosford",
"capacity": 20059,
"surface": "grass",
"address": "Dane Drive 2250 & Central Coast Highway",
"image_path": "https://cdn.sportmonks.com/images/path/to/venue1.png",
"coordinates": null
}
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/venues/{id}?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
Response Attributes
| Name | Type | Description |
|---|---|---|
| id | integer | The id of the venue in the database |
| name | string | The name of the venue |
| city | string | The city where the venue is located |
| capacity | integer | The capacity which the venue can hold |
| surface | string | The surface of the venue |
| address | string | The address of the venue |
| image_path | string | Path to the image of the venue |
| cordinates | object | Cordinates of the venue |
Get Venue By Season ID
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/venues/season/1?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": [
{
"id": 2,
"name": "The Spiers & Hartwell Jubilee Stadium",
"surface": "grass",
"address": "Cheltenham Road",
"city": "Evesham, Worcestershire",
"capacity": 2000,
"image_path": null,
"coordinates": null
},
{
"id": 7,
"name": "Cigg-e Stadium",
"surface": "grass",
"address": "Penydarren Road",
"city": "Merthyr Tydfil",
"capacity": 5000,
"image_path": "https://cdn.sportmonks.com/images/soccer/venues/19/307.png",
"coordinates": null
}
]
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/venues/{id}?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
Response Attributes
| Name | Type | Description |
|---|---|---|
| id | integer | The id of the venue in the database |
| name | string | The name of the venue |
| city | string | The city where the venue is located |
| capacity | string | The capacity which the venue can hold |
| surface | string | The surface of the venue |
| address | string | The address of the venue |
| image_path | string | Path to the image of the venue |
| cordinates | object | Cordinates of the venue |
Rounds
Leagues can be split up in rounds representing a week a game is played in. With this endpoint we give you a ability to request data for a single round as well as all rounds of a season.
Make sure to replace d4ksomxFumF6veb..... with your API key.
Get Round By ID
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/rounds/1?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": {
"id": 1,
"name": 1,
"league_id": 5,
"season_id": 1,
"stage_id": 7,
"start": "2018-10-23",
"end": "2018-12-19"
}
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/rounds/{id}?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
| includes | false | This is the relationship that can be included. eg fixtures, results, season or league |
Response Attributes
| Name | Type | Description |
|---|---|---|
| id | integer | The id of the round in the database |
| name | integer | The name of the round |
| league_id | integr | The league id of this round |
| season_id | integer | The season id of this round |
| stage_id | integer | The stage id of this round |
| start | string | The date when the round starts |
| end | string | The date when the round ends |
Get Round By Season ID
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/rounds/season/1?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": [
{
"id": 1,
"name": 1,
"league_id": 5,
"season_id": 1,
"stage_id": 7,
"start": "2018-10-23",
"end": "2018-12-19"
},
{
"id": 2,
"name": 2,
"league_id": 5,
"season_id": 1,
"stage_id": 7,
"start": "2018-08-11",
"end": "2018-08-12"
}
]
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/rounds/season/{id}?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
| includes | false | This is the relationship that can be included. eg fixtures, results, season or league |
Response Attributes
| Name | Type | Description |
|---|---|---|
| id | integer | The id of the round in the database |
| name | integer | The name of the round |
| league_id | integr | The league id of this round |
| season_id | integer | The season id of this round |
| stage_id | integer | The stage id of this round |
| start | string | The date when the round starts |
| end | string | The date when the round ends |
Stages
This endpoint represents the stages of a season under the leagues hosted by the API.
Leagues can be split up in stages representing a period a game is played in. With this endpoint we give you a ability to request data for a single stages as well as all stages of a season.
Make sure to replace d4ksomxFumF6veb..... with your API key.
Get Stage By ID
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/stages/1?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": {
"id": 1,
"name": "Regular Season",
"type": "Group Stage",
"league_id": 12,
"season_id": 11
}
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/stages/{id}?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
| include | false | This is the relationship that can be included. eg fixtures, results, league or season |
Response Attributes
| Name | Type | Description |
|---|---|---|
| id | integer | The id of the stage in the database |
| name | string | The name of the stage |
| league_id | integer | The id of the league hosting this stage |
| season_id | integer | The id of the season hosting this stage |
| type | string | The type of the stage |
Get Stage By Season ID
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/stages/season/1?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": [
{
"id": 7,
"name": "Europa League Play-offs - Final",
"type": "Knock Out",
"league_id": 3,
"season_id": 1
},
{
"id": 8,
"name": "Europa League Play-offs - Semi-finals",
"type": "Knock Out",
"league_id": 2,
"season_id": 1
}
]
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/stages/{id}?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
| include | false | This is the relationship that can be included. eg fixtures, results, league or season |
Response Attributes
| Name | Type | Description |
|---|---|---|
| id | integer | The id of the stage in the database |
| name | string | The name of the stage |
| league_id | integer | The id of the league hosting this stage |
| season_id | integer | The id of the season hosting this stage |
| type | string | The type of the stage |
Standings
Standings represent the progression teams are making during a season. Standings can be returned in 2 formats. We have the standings for normal domestic leagues, but besides that we also have standings for cups which might have a little different response. Make sure to checkout standings for both types if cups are also part of your subscription.
At this moment historical standings older than the 2016/2017 season are not yet calculated for every league. Those will be added soon.
Please note that when using include options you need to prefix the include with standings.
Make sure to replace d4ksomxFumF6veb..... with your API key.
Get Standings by Season id
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/standings/season/1?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": [
{
"name": "Regular Season",
"league_id": 2,
"season_id": 1,
"stage_id": 7,
"stage_name": "Regular Season",
"standings": {
"data": [
{
"position": 1,
"team_id": 85,
"team_name": "København",
"round_id": 14,
"round_name": 17,
"group_id": null,
"group_name": null,
"overall": {
"games_played": 17,
"won": 12,
"draw": 2,
"lost": 3,
"goals_scored": 37,
"goals_against": 17
},
"home": {
"games_played": 8,
"won": 7,
"draw": 0,
"lost": 1,
"goals_scored": 23,
"goals_against": 9
},
"away": {
"games_played": 9,
"won": 5,
"draw": 2,
"lost": 2,
"goals_scored": 14,
"goals_against": 8
},
"total": {
"goal_difference": "+20",
"points": 38
},
"result": "Championship Round",
"points": 38,
"recent_form": "WDWWW",
"status": "up"
},
{
"position": 2,
"team_id": 35,
"team_name": "Midtjylland",
"round_id": 14,
"round_name": 17,
"..."
"result": "Championship Round",
"points": 35,
"recent_form": "LWDWW",
"status": "down"
}
]
}
}
]
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/standings/season/{id}?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
| include | false | This is the relationship that can be included. eg team, league, round, stage or season |
Response Attributes
| Name | Type | Description |
|---|---|---|
| name | string | The name of the standing |
| league_id | integer | The id of the league associated with this standing |
| season_id | integer | The id of the season associated with this standing |
| stage_id | integer | The id of the stage associated with this standing |
| stage_name | string | The name of the stage associated with this standing |
| standings | object | Details of the standings. Below are the attributes of a standing |
| position | integer | The position of the standing |
| team_id | integer | The team id of the standing |
| team_name | string | The team name of the standing |
| round_id | integer | The round id of the standing |
| round_name | integer | The name of the round in this standing |
| group_id | integer | The group id of this standing |
| group_name | string | The group name of the standing |
| overall | object | The overall standings of this season. It includes attributes such as games_played, won, draw, lost, goals_scored, goals_against |
| home | object | The home standings of this season. It includes attributes such as games_played, won, draw, lost, goals_scored, goals_against |
| away | object | The away standings of this season. It includes attributes such as games_played, won, draw, lost, goals_scored, goals_against |
| total | object | The total standings of this season. It includes attributes such as goal_difference and points |
| result | string | The standing result |
| points | string | The number of points for this standing |
| recent_form | string | The recent form of this standing |
| status | string | The status of this standing |
Get Live Standings by Season id
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/standings/season/live/1?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": [
{
"position": 1,
"played": 17,
"team_id": 1,
"team_name": "København",
"short_code": "COP",
"team_logo": "https://cdn.sportmonks.com/images/path-to-team-1.png",
"goals": "37:17",
"goal_diff": 20,
"wins": 12,
"lost": 3,
"draws": 2,
"points": 38,
"description": "Next Round",
"fairplay_points_lose": 20
}
{
"position": 2,
"played": 17,
"team_id": 2,
"team_name": "Midtjylland",
"short_code": "FCM",
"team_logo": "https://cdn.sportmonks.com/images/path-to-team-2.png",
"goals": "42:17",
"goal_diff": 25,
"wins": 10,
"lost": 2,
"draws": 5,
"points": 35,
"description": "Next Round",
"fairplay_points_lose": 34
}
]
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/standings/season/live/{id}?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
| include | false | This is the relationship that can be included. eg team, league, round, stage or season |
Response Attributes
| Name | Type | Description |
|---|---|---|
| position | integer | The position of the standing |
| played | integer | The number of games played in the standing |
| team_id | integer | The team id of the standing |
| team_name | string | The name of the team in the standing |
| short_code | string | The short code of the team in the standing |
| team_logo | string | A url to the team's logo |
| goals | string | The goals scored in this standing. Team vs opponent separated by colon |
| goal_diff | integer | The difference between the team's goals and the opponents' goals in the season |
| wins | integer | The number of wins this team has made in this season |
| lost | integer | The number of times this team has lost in this season |
| draws | integer | The number of times this team has drawn in this season |
| points | integer | The number of points this team has collected in this season |
| description | string | The description of the standing |
| fairplay_points_lose | integer | The number of points this team can lose on fair play |
Topscorers
Provides you with accurate information of goals, cards and assists topscorers. This endpoint returns the top 25 players and they can all be included at once or separately.
Make sure to replace d4ksomxFumF6veb..... with your API key.
Get Top Scorers for the Season
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/topscorers/season/1?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": {
"id": 1,
"name": "2018/2019",
"league_id": 23,
"is_current_season": true,
"current_round_id": 14,
"current_stage_id": 17,
"goalscorers": {
"data": [
{
"position": 1,
"player_id": 6,
"team_id": 2,
"stage_id": 7,
"goals": 12,
"penalty_goals": 1
},
{
"position": 2,
"player_id": 1,
"team_id": 8,
"stage_id": 7,
"goals": 10,
"penalty_goals": 0
}
]
},
"assistantscorers": {
"data": [
{
"position": 1,
"player_id": 9,
"team_id": 2,
"stage_id": 7,
"assists": 4
},
{
"position": 2,
"player_id": 16,
"team_id": 8,
"stage_id": 7,
"assists": 3
}
]
},
"cardscorers": {
"data": [
{
"position": 1,
"player_id": 12,
"team_id": 2,
"stage_id": 7,
"yellowcards": 2,
"redcards": 1
},
{
"position": 2,
"player_id": 4,
"team_id": 8,
"stage_id": 7,
"yellowcards": 5,
"redcards": 0
}
]
}
}
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/topscorers/season/{id}?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
| include | false | This is the relationship that can be included. eg goalscorers.player, goalscorers.team *goalscorers can also be changed to cardscorers, assistscorers |
| stage_id | false | One or more (comma separated list of) stage id(s) to return data for |
Response Attributes
| Name | Type | Description |
|---|---|---|
| id | integer | The id of the season in the database |
| name | string | The name of the season |
| league_id | integer | The id of the league associated with this season |
| is_current_season | boolean | Is this the current season? |
| current_stage_id | integer | The id of the current stage |
| current_round_id | integer | The id of the current round |
| goalscorers | object | Contains the details of the goal scorers. Including position, player_id, team_id, stage_id, goals and penalty_goals |
| assistantscorers | object | Contains the details of the assistant scorers. Including position, player_id, team_id, stage_id and assists |
| cardscorers | object | Contains the details of the players who got cards. Including position, player_id, team_id, stage_id, yellowcards and redcards |
Get Aggregated Top Scorers for the Season
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/topscorers/season/1/aggregated?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": {
"id": 1,
"name": "2018/2019",
"league_id": 23,
"is_current_season": true,
"current_round_id": 14,
"current_stage_id": 17,
"aggregatedGoalscorers": {
"data": [
{
"position": 1,
"player_id": 6,
"team_id": 2,
"stage_id": 7,
"goals": 12,
"penalty_goals": 1
},
{
"position": 2,
"player_id": 1,
"team_id": 8,
"stage_id": 7,
"goals": 10,
"penalty_goals": 0
}
]
},
"aggregatedAssistantscorers": {
"data": [
{
"position": 1,
"player_id": 9,
"team_id": 2,
"stage_id": 7,
"assists": 4
},
{
"position": 2,
"player_id": 16,
"team_id": 8,
"stage_id": 7,
"assists": 3
}
]
},
"aggregatedCardscorers": {
"data": [
{
"position": 1,
"player_id": 12,
"team_id": 2,
"stage_id": 7,
"yellowcards": 2,
"redcards": 1
},
{
"position": 2,
"player_id": 4,
"team_id": 8,
"stage_id": 7,
"yellowcards": 5,
"redcards": 0
}
]
}
}
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/topscorers/season/{id}/aggregated?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
| include | false | This is the relationship that can be included. eg aggregatedGoalscorers.player, aggregatedGoalscorers.team *aggregatedGoalscorers can also be changed to aggregatedCardscorers, aggregatedAssistscorers |
Response Attributes
| Name | Type | Description |
|---|---|---|
| id | integer | The id of the season in the database |
| name | string | The name of the season |
| league_id | integer | The id of the league associated with this season |
| is_current_season | boolean | Is this the current season? |
| current_stage_id | integer | The id of the current stage |
| current_round_id | integer | The id of the current round |
| aggregatedGoalscorers | object | Contains the details of the aggregated goal scorers. Including position, player_id, team_id, stage_id, goals and penalty_goals |
| aggregatedAssistantscorers | object | Contains the details of the aggregated assistant scorers. Including position, player_id, team_id, stage_id and assists |
| aggregatedCardscorers | object | Contains the details of the aggregated players who got cards. Including position, player_id, team_id, stage_id, yellowcards and redcards |
Video Highlights
Links to video's posted on social media platforms representing important events happening during a game. It can contain video's from goals, yellow & red cards or any other event. In some occasions a compilation of events is also provided.
Video highlights is a community feature which basically means that we cannot guarantee them.
Make sure to replace d4ksomxFumF6veb..... with your API key.
Get Video Highlights
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/video_highlights?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": [
{
"fixture_id": 1,
"location": "https://cc.sporttube.com/link-to-video-1",
"created_at": {
"date": "2018-11-11 21:38:45.000000",
"timezone_type": 3,
"timezone": "UTC"
}
},
{
"fixture_id": 2,
"location": "https://cc.sporttube.com/link-to-video-1",
"created_at": {
"date": "2018-10-21 20:13:53.000000",
"timezone_type": 3,
"timezone": "UTC"
}
}
]
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/video_highlights?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
| include | false | This is the relationship that can be included. eg fixture |
Response Attributes
| Name | Type | Description |
|---|---|---|
| fixture_id | integer | The id of the fixture related to this video |
| location | string | The location of the video hightlight |
| created_at | object | Details to do with the time when the video was streaming |
Commentaries
Textual representation of actions taken on the pitch. They are marked as important or goal if they meet that criteria.
You can use a REST service like Google translate to translate the commentaries into your preferred language.
Make sure to replace d4ksomxFumF6veb..... with your API key.
Get Commentaries By Fixture Id
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/commentaries/fixture/1?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": [
{
"fixture_id": 1,
"important": false,
"order": 10,
"goal": false,
"minute": 84,
"extra_minute": null,
"comment": "Substitution - Celtic. Nir Bitton for Odsonne Edouard."
}
{
"fixture_id": 1,
"important": false,
"order": 9,
"goal": false,
"minute": 77,
"extra_minute": null,
"comment": "Substitution - Partick Thistle. Chris Erskine for Miles Storey."
}
]
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/commentaries/fixture/{id}?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
Response Attributes
| Name | Type | Description |
|---|---|---|
| fixture_id | integer | The id of the fixture related to this commentary |
| important | boolean | Is this commentary important? |
| order | integer | |
| goal | boolean | Is this commentary a goal? |
| minute | integer | The minute when this commentary was recorded |
| extra_minute | integer | What extra minute was this commentary made |
| comment | string | The comment for this commentary |
Head 2 Head
Usefull information used by a lot of tipster is HEAD2HEAD data. With this API you have the possibility to load all previous occurences between 2 teams. Since this is all about fixtue data it's also possible to load relational data via includes, so that you will have a complete view of historical games between the teams.
Make sure to replace d4ksomxFumF6veb..... with your API key.
Get Head 2 Head
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/head2head/1/2?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": [
{
"id": 1,
"league_id": 2,
"season_id": 4,
"stage_id": 1,
"round_id": 14,
"group_id": 9,
"aggregate_id": 8,
"venue_id": 29,
"referee_id": 18,
"localteam_id": 39,
"visitorteam_id": 38,
"weather_report": null,
"commentaries": false,
"attendance": null,
"pitch": null,
"winning_odds_calculated": false,
"formations": {
"localteam_formation": null,
"visitorteam_formation": null
},
"scores": {
"localteam_score": 0,
"visitorteam_score": 0,
"localteam_pen_score": 0,
"visitorteam_pen_score": 0,
"ht_score": null,
"ft_score": null,
"et_score": null
},
"time": {
"status": "NS",
"starting_at": {
"date_time": "2018-11-23 18:00:00",
"date": "2018-11-23",
"time": "18:00:00",
"timestamp": "1542996000",
"timezone": "UTC"
},
"minute": null,
"second": null,
"added_time": null,
"extra_minute": null,
"injury_time": null
},
"coaches": {
"localteam_coach_id": null,
"visitorteam_coach_id": null
},
"standings": {
"localteam_position": 13,
"visitorteam_position": 7
},
"leg": "1/1",
"colors": null,
"deleted": false
},
{
"id": 3,
"league_id": 12,
"season_id": 14,
"stage_id": 11,
"round_id": 4,
"..."
"formations": {
"localteam_formation": "4-4-2",
"visitorteam_formation": "3-5-2"
},
"scores": {
"localteam_score": 1,
"visitorteam_score": 0,
"localteam_pen_score": 0,
"visitorteam_pen_score": 0,
"ht_score": "1-0",
"ft_score": "1-0",
"et_score": null
},
"..."
"leg": "1/1",
"colors": null,
"deleted": false
}
]
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/head2head/{team1id}/{team2id}?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
| include | false | This is the relationship that can be included. eg localTeam, visitorTeam, substitutions, goals, cards, other, lineup, bench, stats, comments, tvstations, highlights, league, season, round, stage, referee, events, venue, trends |
Response Attributes
| Name | Type | Description |
|---|---|---|
| id | integer | The id of the fixture in the database |
| league_id | integer | The id of the league associated with this fixture |
| season_id | integer | The id of the season associated with this fixture |
| stage_id | integer | The id of the stage associated with this fixture |
| round_id | string | round id of the fixture |
| group_id | integer | The id of the group associated with this fixture |
| aggregate_id | integer | The id of the aggregate associated with this fixture |
| venue_id | integer | The id of the venue for this fixture |
| referee_id | integer | The id of the referee for this fixture |
| localteam_id | integer | Id of the team playing at home |
| visitorteam_id | integer | Id of the team played away |
| weather_report | array | report of the weather |
| commentaries | boolean | Are there commentaries? |
| attendance | string | the attendance of the match |
| pitch | string | the name of the pitch |
| winning_odds_calculated | boolean | are winning odds calculated? |
| formations | object | an object containing local team formations and visitor team formations |
| scores | object | an object containing the score breakdown |
| time | object | an object containing details about time |
| coaches | object | an object containing details of local coach and visiting coach |
| standings | object | an object containing local team position and visitor team position |
| colors | object | the colors of the teams |
TV Stations
This endpoint will return all TV stations we know of that broadcast the requested game.
Make sure to replace d4ksomxFumF6veb..... with your API key.
Get TV Stations
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/tvstations/fixture/2?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": [
{
"fixture_id": 2,
"tvstation": "bet365"
},
{
"fixture_id": 2,
"tvstation": "Unibet"
}
]
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/tvstations/fixture/{id}?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
| include | false | This is the relationship that can be included. eg fixture |
Response Attributes
| Name | Type | Description |
|---|---|---|
| fixture_id | integer | The id of the fixture related to this video |
| tvstation | string | The name of the TV station that broadcast the game |
Bookmakers
Extremely useful for administrative purposes is this endpoint to check the availability of bookmakers. You can request all bookmakers at once or just by id.
Make sure to replace d4ksomxFumF6veb..... with your API key.
Get All Bookmakers
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/bookmakers?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": [
{
"id": 1,
"name": "10Bet",
"logo": null
},
{
"id": 2,
"name": "bet365",
"logo": null
}
]
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/bookmakers?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
Response Attributes
| Name | Type | Description |
|---|---|---|
| id | integer | The id of the bookmaker |
| name | string | The name of the bookmaker |
| logo | string | The logo of the bookmaker |
Get Bookmaker by id
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/bookmakers/1?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": {
"id": 1,
"name": "10Bet",
"logo": null
}
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/bookmakers/1?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
Response Attributes
| Name | Type | Description |
|---|---|---|
| id | integer | The id of the bookmaker |
| name | string | The name of the bookmaker |
| logo | string | The logo of the bookmaker |
Markets
Extremely useful for administrative purposes is this endpoint to check the availability of markets. You can request all markets at once or just by id.
Make sure to replace d4ksomxFumF6veb..... with your API key.
Get All Markets
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/markets?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": [
{
"id": 1,
"name": "Over/Under",
},
{
"id": 2,
"name": "3Way Result",
}
]
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/markets?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
Response Attributes
| Name | Type | Description |
|---|---|---|
| id | integer | The id of the market |
| name | string | The name of the market |
Get Market by id
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/markets/1?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": {
"id": 1,
"name": "Over/Under",
}
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/markets/1?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
Response Attributes
| Name | Type | Description |
|---|---|---|
| id | integer | The id of the market |
| name | string | The name of the market |
In-Play Odds
Usefull information used by a lot of tipster is HEAD2HEAD data. With this API you have the possibility to load all previous occurences between 2 teams. Since this is all about fixtue data it's also possible to load relational data via includes, so that you will have a complete view of historical games between the teams.
Make sure to replace d4ksomxFumF6veb..... with your API key.
Get In-Play Odds by Fixture id
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/odds/inplay/fixture/1?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": [
{
"id": 1,
"name": "Fulltime Result",
"bookmaker": {
"data": [
{
"id": 2,
"name": "bet365",
"odds": {
"data": [
{
"label": "Home",
"info": "Haringey Borough",
"value": "1.02",
"american": "-5000",
"fractional": "1/50",
"suspend": 1,
"description": null,
"handicap": "",
"last_update": {
"date": "2018-11-26 21:32:23.000000",
"timezone_type": 3,
"timezone": "UTC"
}
},
{
"label": "Draw",
"info": "X",
"value": "19.00",
"american": "+1800",
"fractional": "18/1",
"suspend": 1,
"description": null,
"handicap": "",
"last_update": {
"date": "2018-11-26 21:32:23.000000",
"timezone_type": 3,
"timezone": "UTC"
}
},
{
"label": "Away",
"info": "Merstham",
"value": "34.00",
"american": "+3300",
"fractional": "33/1",
"suspend": 1,
"description": null,
"handicap": "",
"last_update": {
"date": "2018-11-26 21:32:23.000000",
"timezone_type": 3,
"timezone": "UTC"
}
}
]
}
}
]
}
}
]
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/odds/inplay/fixture/{id}?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
Response Attributes
| Name | Type | Description |
|---|---|---|
| id | integer | The id of the in-play odd in the database |
| name | string | The name of the in-play odd |
| bookmaker | object | the details of the bookmaker. |
| odds | object | Contains an array of odds mainly home, draw and away. The attributes below are inside the odds object |
| label | string | The label of the odd |
| info | string | The info of the odd, that is the name of the team or X for draw |
| value | string | The value of the odd |
| american | string | |
| fractional | string | |
| suspend | integer | |
| description | string | |
| handicap | string | |
| last_update | object | An object representing the time of the last update |
Pre-Match Odds
Odds are used to add betting functionality to your application. We offer the ability to request them per fixture or per fixture and bookmaker. Another option to get information about odds is to use the proper include on any fixture related endpoint. Using odds or flatOdds will enrich the response of a fixture with all odds we have available.
Make sure to replace d4ksomxFumF6veb..... with your API key.
Get Pre-Match Odds by Fixture id
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/odds/fixture/1?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": [
{
"id": 1,
"name": "3Way Result",
"bookmaker": {
"data": [
{
"id": 3,
"name": "1xbet",
"odds": {
"data": [
{
"label": "1",
"value": "1.77",
"winning": null,
"handicap": null,
"total": null,
"bookmaker_event_id": null,
"last_update": {
"date": "2018-11-26 21:32:23.000000",
"timezone_type": 3,
"timezone": "UTC"
}
},
{
"label": "X",
"value": "3.48",
"winning": null,
"handicap": null,
"total": null,
"bookmaker_event_id": null,
"last_update": {
"date": "2018-11-26 21:32:23.000000",
"timezone_type": 3,
"timezone": "UTC"
}
},
{
"label": "2",
"value": "4.6",
"winning": null,
"handicap": null,
"total": null,
"bookmaker_event_id": null,
"last_update": {
"date": "2018-11-26 21:32:23.000000",
"timezone_type": 3,
"timezone": "UTC"
}
}
]
}
}
]
}
}
]
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/odds/inplay/fixture/{id}?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
Response Attributes
| Name | Type | Description |
|---|---|---|
| id | integer | The id of the pre-match odd in the database |
| name | string | The name of the match odd. Either 3Way Result or Over/Under |
| bookmaker | object | The details of the bookmaker. It includes the id of the bookmarker, the name and the odds for it |
| odds | object | Contains an array of odds mainly home, draw, away, over or under. The attributes below are inside the odds object |
| label | string | The label of the odd |
| info | string | The info of the odd, that is the name of the team or X for draw. |
| value | string | The value of the odd |
| american | string | |
| fractional | string | |
| suspend | integer | |
| description | string | |
| handicap | string | |
| last_update | object | An object representing the time of the last update |
Get Pre-Match Odds by Fixture and Bookmaker
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/odds/fixture/1/bookmaker/1?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": [
{
"id": 1,
"name": "3Way Result",
"bookmaker": {
"data": [
{
"id": 2,
"name": "bet365",
"odds": {
"data": [
{
"label": "1",
"value": "1.8",
"winning": null,
"handicap": null,
"total": null,
"bookmaker_event_id": null,
"last_update": {
"date": "2018-11-26 21:32:23.000000",
"timezone_type": 3,
"timezone": "UTC"
}
},
{
"label": "X",
"value": "3.4",
"winning": null,
"handicap": null,
"total": null,
"bookmaker_event_id": null,
"last_update": {
"date": "2018-11-26 21:32:23.000000",
"timezone_type": 3,
"timezone": "UTC"
}
},
{
"label": "2",
"value": "4",
"winning": null,
"handicap": null,
"total": null,
"bookmaker_event_id": null,
"last_update": {
"date": "2018-11-26 21:32:23.000000",
"timezone_type": 3,
"timezone": "UTC"
}
}
]
}
}
]
}
}
]
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/odds/inplay/fixture/{id}/bookmaker/{id}?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
Response Attributes
| Name | Type | Description |
|---|---|---|
| id | integer | The id of the pre-match odd in the database |
| name | string | The name of the match odd. Either 3Way Result or Over/Under |
| bookmaker | object | The details of the bookmaker. It includes the id of the bookmarker, the name and the odds for it |
| odds | object | Contains an array of odds mainly home, draw, away, over or under. The attributes below are inside the odds object |
| label | string | The label of the odd. home, draw, away, 1, X, 2, over or under |
| value | string | The value of the odd |
| winning | string | |
| total | integer | |
| bookmaker_event_id | integer | The id of the bookmaker event |
| handicap | string | |
| last_update | object | An object representing the time of the last update |
Get Pre-Match Odds by Fixture and Market
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/odds/fixture/1/market/1?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": [
{
"id": 1,
"name": "3Way Result",
"bookmaker": {
"data": [
{
"id": 5,
"name": "Unibet",
"odds": {
"data": [
{
"label": "1",
"value": "1.68",
"handicap": "",
"winning": null,
"total": null,
"last_update": {
"date": "2018-11-26 21:32:23.000000",
"timezone_type": 3,
"timezone": "UTC"
}
},
{
"label": "X",
"value": "3.7",
"handicap": "",
"winning": null,
"total": null,
"last_update": {
"date": "2018-11-26 21:32:23.000000",
"timezone_type": 3,
"timezone": "UTC"
}
},
{
"label": "2",
"value": "3.45",
"handicap": "",
"winning": null,
"total": null,
"last_update": {
"date": "2018-11-26 21:32:23.000000",
"timezone_type": 3,
"timezone": "UTC"
}
}
]
}
}
]
}
}
]
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/odds/inplay/fixture/{id}/market/{id}?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
Response Attributes
| Name | Type | Description |
|---|---|---|
| id | integer | The id of the pre-match odd in the database |
| name | string | The name of the match odd. Either 3Way Result or Over/Under |
| bookmaker | object | The details of the bookmaker. It includes the id of the bookmarker, the name and the odds for it |
| odds | object | Contains an array of odds mainly home, draw and away. The attributes below are inside the odds object |
| label | string | The label of the odd |
| value | string | The value of the odd |
| winning | string | |
| total | integer | |
| bookmaker_event_id | integer | The id of the bookmaker event |
| handicap | string | |
| last_update | object | An object representing the time of the last update |
Team Squad
Provides you with accurate information of goals, cards and assists topscorers. This endpoint returns the top 25 players and they can all be included at once or separately.
Make sure to replace d4ksomxFumF6veb..... with your API key.
Get Team Squads for the Season
Example Request:
curl "https://soccer.sportmonks.com/api/v2.0/squad/season/1/1?api_token=d4ksomxFumF6..."
-H "Accept: application/json"
Example Response:
{
"data": [
{
"player_id": 764,
"position_id": 2,
"number": 23,
"captain": 16,
"injured": false,
"minutes": 1750,
"appearences": 20,
"lineups": 20,
"substitute_in": 0,
"substitute_out": 2,
"substitutes_on_bench": 3,
"goals": 1,
"assists": 0,
"saves": 0,
"inside_box_saves": 0,
"dispossesed": 0,
"interceptions": 18,
"yellowcards": 1,
"yellowred": 0,
"redcards": 0,
"tackles": 18,
"blocks": 3,
"hit_post": 0,
"fouls": {
"committed": 0,
"drawn": 18
},
"crosses": {
"total": 57,
"accurate": 1
},
"dribbles": {
"attempts": 26,
"success": 14,
"dribbled_past": 6
},
"duels": {
"total": 177,
"won": 98
},
"passes": {
"total": 639,
"accuracy": 77,
"key_passes": 11
},
"penalties": {
"won": 0,
"scores": 0,
"missed": 0,
"committed": 0,
"saves": 0
}
},
{
"player_id": 5013,
"position_id": 2,
"number": 43,
"captain": 0,
"injured": false,
"minutes": 703,
"appearences": 9,
"lineups": 7,
"substitute_in": 2,
"substitute_out": 0,
"substitutes_on_bench": 5,
"goals": 0,
"assists": 1,
"saves": 0,
"inside_box_saves": 0,
"dispossesed": 0,
"interceptions": 12,
"yellowcards": 0,
"yellowred": 0,
"redcards": 0,
"tackles": 16,
"blocks": 2,
"hit_post": 1,
"fouls": {
"committed": 0,
"drawn": 0
},
"crosses": {
"total": 15,
"accurate": 0
},
"dribbles": {
"attempts": 8,
"success": 5,
"dribbled_past": 8
},
"duels": {
"total": 84,
"won": 47
},
"passes": {
"total": 282,
"accuracy": 69,
"key_passes": 6
},
"penalties": {
"won": 0,
"scores": 0,
"missed": 0,
"committed": 0,
"saves": 0
}
},
]
}
HTTP Request
GET https://soccer.sportmonks.com/api/v2.0/squad/season/{id}/team/{id}?api_token=d4ksomxFumF6...
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| api_token | true | This is the token that will allow you to access the API |
| include | false | This is the relationship that can be included. eg player and position |
Response Attributes
| Name | Type | Description |
|---|---|---|
| player_id | integer | The id of the player |
| position_id | integer | The position of the player |
| number | integer | The number of the player |
| injured | boolean | Was the player injured? |
| minutes | integer | The minutes the player has played |
| appearances | integer | The appearances the player has made |
| lineups | integer | The lineups the player has made |
| substitute_in | integer | The number of substitutes in |
| substitute_out | integer | The number of substitutes out |
| substitutes_on_bench | integer | he number of substitutes on bench |
| goals | integer | The number of goals scored |
| assists | integer | The number of assists given |
| yellowcards | integer | The number of yellow cards given |
| yellowred | integer | The number of yellowred cards given |
| redcards | integer | The number of red cards given |
| dispossesed | integer | The number of tackled by an opponent without attempting to dribble past them |
| hit_post | integer | The Number of times the post has been hit |
| interceptions | integer | Preventing an opponent's pass from reaching their teammates |
| blocks | integer | Being tackled by an opponent without attempting to dribble past them |
| duels - total | integer | The number of duels made by the player |
| duels - won | integer | The number of won duels made by the player |
| dribbles - attempts | integer | The number of total dribble attempts |
| dribbles | success | The number of dribbles taking on an opponent and successfully making it past them while retaining the ball |
| dribbles | past | The number of being dribbled past by an opponent without winning a tackle |
| passes - total | integer | The total number of passes given by a player |
| passes - accuracy | integer | The percentage of attempted passes that successfully found a teammate |
| passes - key | integer | The number of final passes leading to a shot on goal by a teammate |
| penalties - won | integer | |
| penalties - scores | integer | The number of penalties that lead into a goal directly |
| penalties - missed | integer | The number of penalties that did not lead into a goal directly |
| penalties - committed | integer | |
| penalties - saves | integer | The number of penalties saved by the goalkeeper |
Errors
SportMonks uses conventional HTTP response codes to indicate the success or failure of an API request.
In general:
- Codes in the 2xx range indicate success.
- Codes in the 4xx range indicate an error that failed given the information provided.
- Codes in the 5xx range indicate an error with SportMonks' servers.
HTTP status code summary
200 - OK - Everything worked successfully.
400 - Bad Request - The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized - No valid API key provided.
402 - Request Failed - The parameters were valid but the request failed.
404 - Not Found - The requested resource doesn’t exist
409 - Conflict - The request has conflicts (perhaps due to using the same idempotent key).
429 - Too Many Requests - Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 - Server Errors