Overview
The Soccer Season Simulations feed provides season simulation data for a specified tournament calendar. It combines traditional league-table data with probability outputs delivered before and during matches.
Traditional standings data includes position, points, matches played, wins, losses, draws, goals scored, goals conceded, and goal difference. Simulation outputs describe the likelihood of teams winning a league, being relegated, finishing in a specific league-table position, qualifying for worldwide competitions such as the Champions League or Europa League, and other season outcomes.
Problem Statement & Use Cases
This API solves the business problem of turning a live or pre-match league table into a probabilistic season-outcome model. Instead of showing only current standings, applications can expose likely final positions, title probabilities, relegation probabilities, promotion probabilities, and qualification probabilities based on simulated outcomes.
| Use Case |
Description |
| League outcome forecasting |
Build tables that show each club's projected final position and probability of finishing in each rank. |
| Relegation and promotion analysis |
Display probability of relegation, promotion, promotion play-off qualification, or relegation play-off outcomes. |
| European qualification projections |
Show probability of qualifying for competitions such as UEFA Champions League or UEFA Europa League. |
| Predictive editorial and fan dashboards |
Power live articles, broadcast graphics, and fan-facing dashboards that explain how a match changes season-level outcomes. |
Compliance & Guidelines
Authentication and API Security
Use Stats Perform API security guidance, FAQs, API Overview, and Authentication Guide for API behavior, authentication, and authorization rules.
Authentication uses the OAuth method to fetch data.
Polling Frequency
Do not exceed the rate confirmed by Stats Perform. Contact a Stats Perform representative for rate-limit clarification or higher usage requirements.
| Feed |
Tier 15 |
Tier 13 |
| Season Simulations (TM12) |
Once 7 days prior to fixture start date/time; then once every 30 seconds upon kick-off thereafter. |
Once 7 days prior to fixture start date/time; then once every 30 seconds upon kick-off thereafter. |
Request Formatting Rules
All URLs are case-sensitive. URL strings must contain the correct case, operators, and required parameters, or the API returns an error.
| Rule |
Requirement |
| Query string start |
Begin the query parameter string with ? immediately after the feed name. |
| Parameter separator |
Separate query parameters with &. |
| Multiple values: AND |
Use & for multiple values where the API treats them as AND. |
| Multiple values: OR |
Use , only if the parameter supports OR-style multiple values. |
| NOT operator |
Use ! only if the parameter supports negation. |
| Underscore-prefixed parameters |
Include the required _ prefix for parameters such as _fmt and _clbk. |
| Placeholder braces |
Remove placeholder curly braces {} from production API calls. They are documentation examples only. |
| Case sensitivity |
Preserve exact URL, parameter, and operator case. |
| Base URL reference |
The base URL format is {protocol}://{requestDomain}/{feedResource}. |
JSONP Requirements
If _fmt=jsonp is used, it must be combined with the callback parameter _clbk.
| Constraint |
Requirement |
Reason |
| JSONP callback |
Use _fmt=jsonp together with _clbk. |
JSONP requires a callback wrapper function. |
| Fixed callback value |
Use a fixed _clbk value whenever possible. |
Random callback names can reduce cacheability and violate API best-practice logic. |
| JavaScript frameworks |
Override framework-generated random callback names, including defaults from common frameworks such as jQuery. |
Some frameworks generate random JSONP function names unless explicitly configured. |
Endpoints
Base URL
https://api.statsperform.com
Feed Resource
/sdapi/v1/soccerdata/predictions/seasonsimulations
Get Season Simulations by Tournament Calendar UUID
GET /sdapi/v1/soccerdata/predictions/seasonsimulations?tmcl={tournamentCalendarUuid}&{queryParameters}
| Usage |
Feed |
| Get season simulations by tournament calendar UUID. |
/sdapi/v1/soccerdata/predictions/seasonsimulations?tmcl={tournamentCalendarUuid}&{queryParameters} |
Example Request
GET https://api.statsperform.com/sdapi/v1/soccerdata/predictions/seasonsimulations?_fmt={dataFormat}&tmcl={tournamentCalendarUuid}
Query Parameters
This feed uses Global query parameters and the feed-specific query parameter listed below.
The Season Simulations feed must be queried by a specific tournament calendar UUID.
The source documentation refers to querying the /teamStandings feed by tournament calendar UUID, while the endpoint examples use /sdapi/v1/soccerdata/predictions/seasonsimulations.
Required Feed-Specific Parameters
| Query Parameter |
Required |
Description |
Accepted Values / Format |
Example Request |
tmcl |
Yes |
Gets season simulations data for a season by the specified tournament calendar UUID. |
{tournamentCalendarUuid} |
GET https://api.statsperform.com/sdapi/v1/soccerdata/predictions/seasonsimulations?_fmt={dataFormat}&tmcl={tournamentCalendarUuid} |
Global Parameters Used in Examples
| Query Parameter |
Required |
Description |
Accepted Values / Format |
Notes |
_fmt |
Conditional |
Response data format. |
{dataFormat} such as XML, JSON, or JSONP. |
Required in documented examples. |
_clbk |
Conditional |
JSONP callback function name. |
Fixed callback function name. |
Required when _fmt=jsonp. |
Output Schema
The feed response fields are documented using XML element names. JSON responses contain similar fields, but XML-only nodes and attributes may be omitted or represented differently.
`<team
Standings>`
| Property |
Value |
| Nesting |
teamStandings |
| Description |
Required or optional root element of the fields related to team standings. |
| Format behavior |
XML root element. Some attributes are XML-only and not present in JSON. |
| Attribute |
Required |
Description |
Values |
lastUpdated |
Yes |
UTC date and time when the Team Standings feed information or record was last updated. Only present in XML, not JSON. |
Date/Time in format YYYY-MM-DDZ |
xmlns:soccerdata |
Yes |
Schema reference returned for XML only. |
http://www.performgroup.com/schema/soccerdata |
<sport>
| Property |
Value |
| Nesting |
teamStandings/sport |
| Description |
Required root element of the fields related to the sport. |
| Attribute |
Required |
Description |
Values |
id |
Yes |
Unique ID of the sport. |
String; alphanumeric UUID |
<ruleset>
| Property |
Value |
| Nesting |
teamStandings/ruleset |
| Description |
Required root element of the fields related to the sport ruleset. |
| Attribute |
Required |
Description |
Values |
id |
Yes |
Unique ID of the ruleset. |
String; alphanumeric UUID |
<competition>
| Property |
Value |
| Nesting |
teamStandings/competition |
| Description |
Required root element of the fields related to the competition. |
| Attribute |
Required |
Description |
Values |
id |
Yes |
Unique ID of the competition. |
String; alphanumeric UUID |
name |
Yes |
Name of the competition. |
String |
`<tournament
Calendar>`
| Property |
Value |
| Nesting |
teamStandings/tournamentCalendar |
| Description |
Required root element of the fields related to a tournament calendar. |
| XML value |
String giving the tournament calendar name. |
| Attribute |
Required |
Description |
Values |
id |
Yes |
Unique ID of the tournament calendar. |
String; alphanumeric UUID |
startDate |
Yes |
Start date in UTC of the tournament calendar. |
Date in format YYYY-MM-DDZ |
endDate |
Yes |
End date in UTC of the tournament calendar. |
Date in format YYYY-MM-DDZ |
name |
Yes |
Name of the tournament. |
String |
<stages>
| Property |
Value |
| Nesting |
teamStandings/stages |
| Description |
Required root element of the fields related to stages. |
| Attributes |
None |
<stage>
| Property |
Value |
| Nesting |
teamStandings/stages/stage |
| Description |
Required root element of the fields related to the stage. |
| Attribute |
Required |
Description |
Values |
id |
Yes |
Unique ID of the stage. |
String; alphanumeric UUID |
formatId |
Yes |
Unique ID of the stage format. This identifies a specific type of stage; across seasons, a team can have the same format ID but a different stage ID because the stage ID is linked to a specific stage and season. |
String; alphanumeric UUID |
name |
Yes |
Name of the stage. |
String |
vertical |
No |
Provides a competition chronology explaining the order in which rounds or groups are played. Returned only when data is available and applicable. Used to order groups so that Group A or Group 1 appears first, rather than relying on ID or start date ordering. |
Integer |
startDate |
Yes |
Start date in UTC of the stage. |
Date in format YYYY-MM-DDZ |
endDate |
Yes |
End date in UTC of the stage. |
Date in format YYYY-MM-DDZ |
While exceptions may exist, rounds with different vertical IDs are generally not expected to be played at the same time.
<divisions>
| Property |
Value |
| Nesting |
teamStandings/stages/stage/divisions |
| Description |
Required root element of the fields related to divisions. |
| Attributes |
None |
<division>
| Property |
Value |
| Nesting |
teamStandings/stages/stage/divisions/division |
| Description |
Required element providing information about a division. |
| Attribute |
Required |
Description |
Values |
type |
Yes |
Type of the division. |
total, home, away, form-total, form-home, half-time-total, half-time-home, half-time-away, attendance, over-under |
<ranking>
| Property |
Value |
| Nesting |
teamStandings/stages/stage/divisions/division/ranking |
| Description |
Required element holding information about the ranking entry in the division. |
| Attribute |
Required |
Description |
Values |
rank |
Yes |
Rank or position in the division. |
Integer |
rankStatus |
Yes |
Ranking position of the given team. |
String |
rankId |
Yes |
Unique ID relating to the rank status. |
String; alphanumeric UUID |
achievementStatus |
No |
Achievement status related to the ranking. |
Integer |
achievementType |
No |
Achievement type related to the ranking. |
Integer |
achievementStatus1 |
No |
Achievement status 1 related to the rank. |
Integer |
achievementType1 |
No |
Achievement type 1 related to the rank. |
Integer |
achievementStatus2 |
No |
Achievement status 2 related to the rank. |
Integer |
achievementType2 |
No |
Achievement type 2 related to the rank. |
Integer |
achievementStatus3 |
No |
Achievement status 3 related to the rank. |
Integer |
achievementType3 |
No |
Achievement type 3 related to the rank. |
Integer |
achievementStatus4 |
No |
Achievement status 4 related to the rank. |
Integer |
achievementType4 |
No |
Achievement type 4 related to the rank. |
Integer |
achievementStatus5 |
No |
Achievement status 5 related to the rank. |
Integer |
achievementType5 |
No |
Achievement type 5 related to the rank. |
Integer |
lastRank |
Yes |
Value of the last rank in the ranking. |
Integer |
contestantId |
Yes |
Unique ID of the team related to the event. |
String; alphanumeric UUID |
contestantName |
Yes |
Name of the contestant. |
String |
contestantShortName |
Yes |
Short name commonly used to refer to the contestant. |
String |
contestantClubName |
Yes |
Club name of the contestant. |
String |
contestantCode |
Yes |
Three-character code used for the contestant name, often used on TV scoreboards. |
String |
points |
Yes |
Number of points attained in the ranking. |
Dynamic; usually Integer |
matchesPlayed |
Yes |
Number of matches played. |
Integer |
matchesWon |
Yes |
Number of matches won. |
Integer |
matchesLost |
Yes |
Number of matches lost. |
Integer |
matchesDrawn |
Yes |
Number of matches that ended in a draw. |
Integer |
goalsFor |
Yes |
Number of goals scored by or for the contestant. |
Integer |
goalsAgainst |
Yes |
Number of goals scored against or conceded by the contestant. |
Integer |
goalDifference |
Yes |
Difference between goals scored and conceded. Value may be positive, negative, or zero; examples: +1, -2, 0. |
String |
lastSix |
No |
Contestant's last six results in the competition that the match relates to. Uses D for draw, L for lost, and W for won. Example: WLLWDD means win, lost, lost, win, draw, draw. |
String |
`<finish
Predictions>`
| Property |
Value |
| Nesting |
teamStandings/stages/stage/divisions/division/ranking/finishPredictions |
| Description |
Required root element of the fields related to finish predictions in ranking. |
| Attributes |
None |
`<finish
Prediction>`
| Property |
Value |
| Nesting |
teamStandings/stages/stage/divisions/division/ranking/finishPredictions/finishPrediction |
| Description |
Required root element of the fields related to finish predictions. |
| Attribute |
Required |
Description |
Values |
position |
Yes |
Position of the finish prediction. |
Integer |
value |
Yes |
Value of the finish prediction. |
String |
`<rank
Predictions>`
| Property |
Value |
| Nesting |
teamStandings/stages/stage/divisions/division/ranking/rankPredictions |
| Description |
Required root element of the fields related to rank predictions. |
| Attributes |
None |
`<rank
Prediction>`
| Property |
Value |
| Nesting |
teamStandings/stages/stage/divisions/division/ranking/rankPredictions/rankPrediction |
| Description |
Required root element of the fields related to rank entries in predictions. |
| Attribute |
Required |
Description |
Values |
rankStatus |
Yes |
Position or season outcome for the given team, such as promotion, champions, relegation, Champions League qualification, or another rank-related outcome. |
Examples: Promotion, Promotion Play-off, Relegation, Relegation Play-off, UEFA Champions League, UEFA Europe League |
rankId |
Yes |
Unique ID relating to the rank status. Example: Relegation has rank UUID 1xsy07o6mnddbc0p9a02jhojx. |
String |
value |
Yes |
Value of the prediction in the ranking. |
String |
