Overview
The Soccer Team Player Predictions feed returns predictive statistics for teams and players in a specified soccer fixture.
The feed provides predictions for key events such as goals, cards, and penalties; predicted team-statistic totals such as shots, saves, red cards, yellow cards, and corners; and statistics and predictions for individual lineup players.
The feed also returns season averages for the supported statistics at team and player level. Team and fixture predictions are available across the season and are recalculated once per day. Player-related predictions are available for the next upcoming match of a team and are recalculated once per minute after kick-off while the match is being played.
| Included Data Category |
Description |
| Match metadata |
Fixture ID, date, time, coverage level, local date/time, period configuration, and last update timestamp. |
| Competition metadata |
Sport, ruleset, competition, country, tournament calendar, stage, contestants, and venue details. |
| Live match details |
Match status, period, winner, aggregate references, match length, team/player of the match, scores, and period timing. |
| Key events |
Goals, cards, substitutions, and VAR events with player, contestant, period, timing, and Opta event identifiers. |
| Lineups |
Contestant lineup details, team officials, formations, and player metadata. |
| Pre-match predictions |
Team and player prediction targets with season averages before the fixture. |
| Live predictions |
Minute-by-minute prediction snapshots for players and teams during the match. |
| Match extras |
Attendance and match-official details when available. |
Problem Statement & Use Cases
This API solves the business problem of projecting expected team and player outcomes for a soccer fixture before and during play. Instead of relying only on final box-score data, downstream systems can ingest structured predictions and season averages for specific statistics and update those predictions as match context changes.
| Use Case |
Description |
| Pre-match prediction dashboards |
Display projected team and player outcomes for goals, cards, shots, saves, passes, fouls, and other supported statistics before kick-off. |
| Live player-stat widgets |
Update player and team prediction values during a live match using minute-specific prediction snapshots. |
| Lineup-based analytics |
Combine starting lineup, substitute, team-official, and prediction data to analyze expected player contributions. |
| Model feature engineering |
Use prediction targets and season averages as features for downstream forecasting, simulation, editorial, or personalization models. |
Compliance & Guidelines
Authentication and API Security
To comply with Stats Perform API security and best-practice requirements, refer to the Stats Perform FAQs, API Overview, and Authentication Guide.
Authentication uses the OAuth method to fetch data.
Limited Availability
This feed launches with limited availability. Ask your Stats Perform Account Manager for competition availability and commercial/legal availability before integration.
| Constraint |
Detail |
| Competition availability |
Limited at launch and dependent on Stats Perform availability. |
| Commercial/legal review |
Confirm commercial legalities with the account team before using this feed in production. |
Prediction Availability and Refresh Cadence
| Prediction Type |
Availability |
Recalculation Cadence |
| Team and fixture predictions |
Available for the entire season. |
Recalculated once per day. |
| Player predictions |
Available for the team's next upcoming match. |
Recalculated once per minute after kick-off while the match is being played. |
Polling Frequency
Do not exceed the polling rate confirmed by Stats Perform. Contact a Stats Perform representative if higher limits or clarification are required.
| Tier |
Polling Frequency |
| Tier 15 |
Once per day up until fixture start date/time, then once every minute after kick-off. |
| Tier 13 |
Once per day up until fixture start date/time, then once every minute after kick-off. |
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 parameters 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, _clbk, and _rt. |
| 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. |
Fixture Requirement
The /teamplayerpredictions feed must be queried by fixture or match UUID.
| Requirement |
Detail |
| Path parameter method |
Pass the fixture UUID directly in the request path. |
| Query parameter method |
Pass the fixture UUID to the fx query parameter. |
| Minute-specific predictions |
Use min to retrieve prediction values at a specified minute or range of minutes. |
| Statistic filtering |
Use stat to limit the response to one or more supported statistics. |
Endpoints
Base URLs
https://api.statsperform.com
https://api.performfeeds.com
Primary Feed Resource
/sdapi/v1/soccerdata/teamplayerpredictions
Get Team Player Predictions by Fixture UUID Path Parameter
GET /sdapi/v1/soccerdata/teamplayerpredictions/{fixtureUUID}?{queryParameters}
| Usage |
Feed |
| Get team player predictions for a specific fixture using the fixture UUID path parameter. |
/sdapi/v1/soccerdata/teamplayerpredictions/{fixtureUUID}?{queryParameters} |
Get Team Player Predictions by Fixture UUID Query Parameter
GET /sdapi/v1/soccerdata/teamplayerpredictions?fx={fixtureUUID}&{queryParameters}
| Usage |
Feed |
Get team player predictions for a specific fixture using the fx query parameter. |
/sdapi/v1/soccerdata/teamplayerpredictions?fx={fixtureUUID}&{queryParameters} |
Get Detailed Team Player Predictions
GET /soccerdata/teamplayerpredictions/{outletAuthKey}?fx={fixtureUUID}&detailed={yes|no}&_rt={mode}&_fmt={dataFormat}
| Usage |
Feed |
| Get detailed team player predictions using the outlet-authentication feed path. |
/soccerdata/teamplayerpredictions/{outletAuthKey}?fx={fixtureUUID}&detailed={yes|no}&_rt={mode}&_fmt={dataFormat} |
Example Request Patterns
GET https://api.statsperform.com/sdapi/v1/soccerdata/teamplayerpredictions/{fixtureUUID}?_fmt={dataFormat}
GET https://api.statsperform.com/sdapi/v1/soccerdata/teamplayerpredictions?fx={fixtureUUID}&_fmt={dataFormat}
GET https://api.statsperform.com/sdapi/v1/soccerdata/teamplayerpredictions?fx={fixtureUUID}&min={mm}&_fmt={dataFormat}
GET https://api.statsperform.com/sdapi/v1/soccerdata/teamplayerpredictions?fx={fixtureUUID}&min={mm}&stat={statvalue}&_fmt={dataFormat}
GET https://api.performfeeds.com/soccerdata/teamplayerpredictions/{outletAuthKey}?fx={fixtureUUID}&detailed={yes|no}&_rt={mode}&_fmt={dataFormat}
Query Parameters
This feed uses Global query parameters and the feed-specific query parameters listed below.
Query the /teamplayerpredictions feed by fixture UUID using either the path parameter method or the fx query parameter method.
Feed-Specific Query Parameters
| Parameter |
Location |
Description |
Accepted Values / Format |
Example Request |
{fixtureUUID} |
Path |
Get team player predictions for a specific fixture UUID. |
Fixture UUID |
GET https://api.statsperform.com/sdapi/v1/soccerdata/teamplayerpredictions/{fixtureUUID}?_fmt={dataFormat} |
fx |
Query |
Get team player predictions for the specified fixture UUID. |
Fixture UUID |
GET https://api.statsperform.com/sdapi/v1/soccerdata/teamplayerpredictions?fx={fixtureUUID}&_fmt={dataFormat} |
detailed |
Query |
Get the detailed team player prediction for the specified fixture UUID. |
yes, no |
GET https://api.performfeeds.com/soccerdata/teamplayerpredictions/{outletAuthKey}?fx={fixtureUUID}&detailed={yes\|no}&_rt={mode}&_fmt={dataFormat} |
min |
Query |
Get predictive values at a specified point in match time. With min={mm}, the response contains prediction values valid at minute {mm}. With min={mm},{mm}, the response contains all prediction values grouped by minute within the requested range. With min=-1, the response returns all available data for the match. |
Match minute, comma-separated minute range, or -1 |
GET https://api.statsperform.com/sdapi/v1/soccerdata/teamplayerpredictions?fx={fixtureUUID}&min={mm}&_fmt={dataFormat} |
stat |
Query |
Limit the response to a dedicated statistic or an array of statistics. |
yellow_cards, fouls, saves, red_cards, assists, minutes, shots, goals, passes |
GET https://api.statsperform.com/sdapi/v1/soccerdata/teamplayerpredictions?fx={fixtureUUID}&min={mm}&stat={statvalue}&_fmt={dataFormat} |
Global Query Parameters Referenced by This Feed
| Parameter |
Description |
Requirement / Notes |
_fmt |
Response data format. |
Use a supported Stats Perform data format such as XML, JSON, or JSONP. |
_clbk |
JSONP callback function name. |
Required when _fmt=jsonp. Use a fixed callback name. |
_rt |
Runtime or mode parameter used in the detailed endpoint example. |
Used with the api.performfeeds.com detailed request pattern. |
min Parameter Behavior
min Value Pattern |
Response Behavior |
min={mm} |
Returns prediction values valid at the specified match minute. |
min={mm},{mm} |
Returns all prediction values grouped by minute within the specified range. |
min=-1 |
Returns all available data for the match. |
Supported stat Values
| Statistic Value |
Description |
yellow_cards |
Yellow-card predictions or statistics. |
fouls |
Foul predictions or statistics. |
saves |
Save predictions or statistics. |
red_cards |
Red-card predictions or statistics. |
assists |
Assist predictions or statistics. |
minutes |
Minutes-played predictions or statistics. |
shots |
Shot predictions or statistics. |
goals |
Goal predictions or statistics. |
passes |
Pass predictions or statistics. |
Output Schema
The feed response fields are documented using XML element names. JSON responses contain similar fields, but XML-only wrapper elements may be omitted or represented differently.
<match>
| Property |
Value |
| Format |
XML only wrapper or XML-specific behavior |
| Nesting |
match |
| Description |
Root element of the fields related to the match (XML only) |
| Note |
Not present in JSON feed response, where the root element is matchInfo |
| Attribute |
Required |
Description |
Values |
xmlns:soccerdata (XML only) |
Yes |
Schema reference - returned for XML only |
http://www.performgroup.com/schema/soccerdata |
`<match
Info>`
| Property |
Value |
| Nesting |
match/matchInfo |
| Description |
Root element of the fields related to the match |
| Attribute |
Required |
Description |
Values |
id |
Yes |
Unique ID (UUID) of the match |
String (Alphanumeric - UUID) |
coverageLevel |
Yes |
The match coverage level |
String |
date |
Yes |
The date (UTC) of the fixture/match |
Date - in the format: YYYY-MM-DDZ |
time |
No |
The start time (UTC) of the fixture/match |
Time - in the format: hh:mm:ssZ |
localDate |
Yes |
The local date of the fixture/match |
Date - in the format: YYYY-MM-DD |
localTime |
No |
The local time of the fixture/match |
Time - in the format: hh:mm:ss |
week |
No |
The week in which the match is taking place |
String |
numberOfPeriods |
No |
The number of periods that will be played. For example, a regular soccer match will have two periods |
Integer |
periodLength |
No |
The duration of a period. For example, the duration of a period in a regular soccer match is 45 minutes |
Integer |
lastUpdated |
Yes |
The UTC date and time (timestamp) of when the match information/record was last updated |
Date/Time - in the format: YYYY-MM-DDThh:mm:ssZ |
<description>
| Property |
Value |
| Nesting |
match/matchInfo/description |
| Description |
Description of the match. Value: string giving the description - for example, the contestant names |
| Attribute |
Required |
Description |
Values |
| None |
No |
This element has no documented attributes. |
N/A |
<sport>
| Property |
Value |
| Nesting |
match/matchInfo/sport |
| Description |
Root element of the fields related to the sport |
| Attribute |
Required |
Description |
Values |
id |
Yes |
Unique ID (UUID) of the sport |
String (Alphanumeric - UUID) |
name (JSON only) |
Yes |
Name of the sport |
String |
<ruleset>
| Property |
Value |
| Nesting |
match/matchInfo/ruleset |
| Description |
Root element of the fields related to the ruleset |
| Attribute |
Required |
Description |
Values |
id |
Yes |
Unique ID (UUID) of the ruleset |
String (Alphanumeric - UUID) |
name (JSON only) |
Yes |
Name of the ruleset |
String |
<competition>
| Property |
Value |
| Nesting |
match/matchInfo/competition |
| Description |
Root element of the fields related to the competition |
| Attribute |
Required |
Description |
Values |
id |
Yes |
Unique ID (UUID) of the competition |
String (Alphanumeric - UUID) |
name |
Yes |
The name of the competition |
String |
knownName |
No |
The known name of the competition |
String |
competitionCode |
Yes |
The short three-digit competition code |
String |
competitionFormat |
Yes |
The format of the competition - one of the following values: Domestic league | Domestic cup | Domestic super cup | International cup | International super cup |
String |
<country> under <competition>
| Property |
Value |
| Format |
XML only |
| Nesting |
match/matchInfo/competition/country |
| Description |
Root element of the fields related to the country that the competition is based in. Value (XML only): String giving the country name |
| Attribute |
Required |
Description |
Values |
id |
Yes |
Unique ID (UUID) of the country that the competition is based in |
String (Alphanumeric - UUID) |
name (JSON only) |
Yes |
Name of the country |
String |
`<tournament
Calendar>`
| Property |
Value |
| Format |
XML only |
| Nesting |
match/matchInfo/tournamentCalendar |
| Description |
Root element of the fields related to a tournament calendar. Value (XML only): String giving the tournament calendar name |
| Attribute |
Required |
Description |
Values |
id |
Yes |
Unique ID (UUID) of the tournament calendar |
String (Alphanumeric - UUID) |
startDate |
Yes |
The start date (UTC) of the tournament calendar |
Date - in the format: YYYY-MM-DDZ |
endDate |
Yes |
The end date (UTC) of the tournament calendar |
Date - in the format: YYYY-MM-DDZ |
name (JSON only) |
Yes |
Name of the tournament calendar |
String |
<stage>
| Property |
Value |
| Nesting |
match/matchInfo/stage |
| Description |
Root element of the fields related to the stage |
| Attribute |
Required |
Description |
Values |
id |
Yes |
Unique ID (UUID) of the stage |
String (Alphanumeric - UUID) |
formatId |
Yes |
Unique ID (UUID) of the stage format. This is an identifier for a specific type of stage - despite being played in different seasons, a team (contestant) can have the same format ID but a different stage ID (the stage ID is linked with stage and season). |
String (Alphanumeric - UUID) |
startDate |
Yes |
The start date (UTC) of the stage |
Date - in the format: YYYY-MM-DDZ |
endDate |
Yes |
The end date (UTC) of the stage |
Date - in the format: YYYY-MM-DDZ |
name (JSON only) |
Yes |
Name of the stage |
String |
<contestants>
| Property |
Value |
| Format |
XML only |
| Nesting |
match/matchInfo/contestants |
| Description |
Root element of the fields related to contestants (XML only). |
| Attribute |
Required |
Description |
Values |
| None |
No |
This element has no documented attributes. |
N/A |
<contestant>
| Property |
Value |
| Nesting |
match/matchInfo/contestants/contestant |
| Description |
Root element of the fields related to a contestant. This element is optional (it may not always be returned in the feed - for example if the match is scheduled but contestants are not yet known, in which case the record will be updated once known) |
| Attribute |
Required |
Description |
Values |
id |
Yes |
Unique ID (UUID) of the contestant |
String (Alphanumeric - UUID) |
name |
Yes |
The name of the contestant |
String |
shortName |
No |
The short name commonly used to refer to the contestant |
String |
officialName |
Yes |
The official name of the contestant |
String |
code |
No |
The 3-character code used for the name of the contestant - it is often used on TV scoreboards |
String |
position |
Yes |
Indicates the position of the contestant as either the home or away side, in the list of contestants |
String - one of the following: home | away |
<country> under <contestant>
| Property |
Value |
| Format |
XML only |
| Nesting |
match/matchInfo/contestants/contestant/country |
| Description |
Root element of the fields related to a contestant - this element is optional (it may not always be returned in the feed). Value (XML only): String giving the country name |
| Attribute |
Required |
Description |
Values |
id |
Yes |
Unique ID (UUID) of the country the contestant is from |
String (Alphanumeric - UUID) |
name (JSON only) |
Yes |
Name of the country |
String |
<venue>
| Property |
Value |
| Format |
XML only wrapper or XML-specific behavior |
| Nesting |
match/matchInfo/venue |
| Description |
Root element of the fields related to a venue - this element is optional (it may not always be returned in the feed). Value (XML only): String giving the venue name; in JSON/JSONP it is returned under shortName instead |
| Attribute |
Required |
Description |
Values |
id |
Yes |
Unique ID (UUID) of the venue |
String (Alphanumeric - UUID) |
neutral |
Yes |
Whether or not the venue is neutral: yes (is neutral - the venue is associated with one of the contestants) no (not neutral - the venue is associated with one of the contestants) |
String - one of the following: no | yes |
longName |
Yes |
The long/extended name of the venue |
String |
latitude |
No |
The latitude coordinates for the location of the venue |
String |
longitude |
No |
The longitude coordinates for the location of the venue |
String |
shortName (JSON only) |
Yes |
The short name of the venue |
String |
`<live
Data>`
| Property |
Value |
| Nesting |
match/liveData |
| Description |
Root element of the fields related to live data |
| Note |
If no live data is available (for example, if the fixture is scheduled but is not playing or has not been played) then an empty liveData element is returned and some sub-elements will not be returned. However, when new information is available the feed will be updated - see our polling frequency recommendations for more information. |
| Attribute |
Required |
Description |
Values |
| None |
No |
This element has no documented attributes. |
N/A |
`<match
Details>`
| Property |
Value |
| Nesting |
match/liveData/matchDetails |
| Description |
Root element of the fields related to the match details |
| Attribute |
Required |
Description |
Values |
periodId |
Yes |
The current match period - one of the following: • 1 (First half) • 2 (Second half) • 3 (Extra time - first half) • 4 (Extra time - second half) • 5 (Penalty shootout) • 10 (Half time) • 11 (End of second half - before extra time) • 12 (Extra time half time) • 13 (End of extra time - before penalties) • 14 (Full time) • 16 (Pre-match) |
Integer |
matchStatus |
Yes |
The status of the match - one of the following: Fixture | Playing | Played | Cancelled | Postponed | Suspended | Awarded Note - New value of Awarded available - it is used for matches that do not take place or when one of the contestants involved gets 'awarded' the match with an associated result. |
String |
winner |
No |
The outcome of the match. Note: This attribute is only shown when the match is completed (when matchStatus="Played") |
String - one of the following: home | away | draw |
leg |
No |
The leg of the competition a match is being played in. |
Integer |
aggregateId |
No |
A unique identifier used to group and link both legs of a paired soccer match (e.g., home and away games in a two-legged tie). |
String (Alphanumeric - UUID) |
previousAggregateIds |
No |
It contain aggregated IDs for previous rounds of the fixture. (e.g., previousRoundAggregateId1, previousRoundAggregateId2) |
String |
previousMatchIds |
No |
UUID of ‘Previous Match’ |
String (Alphanumeric - UUID) |
advancementAggregateId |
No |
A reference to the aggregateId indicating which aggregate winner will advance to the next round or stage in a paired soccer match series. |
String (Alphanumeric - UUID) |
matchLengthMin |
No |
The total number of full minutes played in the match (includes stoppage time). Note: This attribute is only shown when the match is completed (when matchStatus="Played") |
Integer |
matchLengthSec |
No |
The number of seconds in addition to the full minutes played in the match (includes stoppage time). Note: This attribute is only shown when the match is completed (when matchStatus="Played") |
Integer |
contestantOfTheMatchId |
No |
UUID of ‘Team of the Match’ |
String (Alphanumeric - UUID) |
playerOfTheMatch |
No |
Name of ‘Player of the Match’ |
String |
playerOfTheMatchId |
No |
UUID of ‘Player of the Match’ |
String (Alphanumeric - UUID) |
goalkeeperOfTheMatch |
No |
Name of ‘Goal Keeper of the Match |
String |
goalkeeperOfTheMatchId |
No |
UUID of ‘Goal Keeper of the Match’ |
String (Alphanumeric - UUID) |
<periods>
| Property |
Value |
| Format |
XML only wrapper or XML-specific behavior |
| Nesting |
match/liveData/matchDetails/periods |
| Description |
Root element of the fields related to periods in a match (XML only) - this element is optional (it may not always be returned in the feed). |
| Note |
JSON/JSONP: Not present in JSON/JSONP feed response, where the individual period elements are returned instead All formats: The periods and/or period elements are only returned if data is available and if the status (matchStatus) is 'Playing', 'Played', 'Suspended', 'Cancelled', or 'Postponed'. If no data is available (for example, if the fixture is scheduled but is not playing or has not been played) then the liveData element may be empty or some sub-elements will not be returned. However, when new information is available the feed will be updated - see our polling frequency recommendations for more information. |
| Attribute |
Required |
Description |
Values |
| None |
No |
This element has no documented attributes. |
N/A |
<period>
| Property |
Value |
| Nesting |
match/liveData/matchDetails/periods/period |
| Description |
Root element of the fields related to a period in the match - this element is optional (it may not always be returned in the feed). |
| Note |
Only visible if the status (matchStatus) is 'Playing', 'Played', 'Suspended', 'Cancelled', or 'Postponed'. If no data is available (for example, if the fixture is scheduled but is not playing or has not been played) then the liveData element may be empty or some sub-elements will not be returned. However, when new information is available the feed will be updated - see our polling frequency recommendations for more information. |
| Attribute |
Required |
Description |
Values |
id |
Yes |
The match period ID - one of the following: 1 | 2 | 3 | 4 |
Integer |
start |
Yes |
The start date and time of the period (UTC) |
Date/Time - in the format: YYYY-MM-DDThh:mm:ssZ |
end |
Yes |
The end date and time of the period (UTC) |
Date/Time - in the format: YYYY-MM-DDThh:mm:ssZ |
lengthMin |
Yes |
The number of total minutes in the period (includes stoppage time) |
Integer |
lengthSec |
Yes |
The number of seconds in addition to the total minutes in the period (includes stoppage time) |
Integer |
announcedInjuryTime |
No |
Time when injury was announced. |
Integer |
<scores>
| Property |
Value |
| Nesting |
match/liveData/matchDetails/scores |
| Description |
Root element of the fields related to scores - this element is optional (it may not always be returned in the feed). |
| Note |
Only visible if the status (matchStatus) is 'Playing', 'Played', 'Suspended', 'Cancelled', or 'Postponed'. |
| Attribute |
Required |
Description |
Values |
| None |
No |
This element has no documented attributes. |
N/A |
<ht>
| Property |
Value |
| Nesting |
match/liveData/matchDetails/scores/ht |
| Description |
Root element of the fields related to first half scores - this element is optional (it may not always be returned in the feed). |
| Note |
Only visible if the status (matchStatus) is 'Playing', 'Played', 'Suspended', 'Cancelled', or 'Postponed'. |
| Attribute |
Required |
Description |
Values |
home |
Yes |
The half-time score of the home team |
Integer |
away |
Yes |
The half-time score of the away team |
Integer |
<ft>
| Property |
Value |
| Nesting |
match/liveData/matchDetails/scores/ft |
| Description |
Root element of the fields related to the full-time (second half) scores - this element is optional (it may not always be returned in the feed). |
| Attribute |
Required |
Description |
Values |
home |
Yes |
The full-time score of the home team |
Integer |
away |
Yes |
The full-time score of the away team |
Integer |
<total>
| Property |
Value |
| Nesting |
match/liveData/matchDetails/scores/total |
| Description |
Root element of the fields related to the total scores - this element is optional (it may not always be returned in the feed). |
| Note |
Only visible if the status (matchStatus) is 'Playing', 'Played', 'Suspended', 'Cancelled', or 'Postponed'. |
| Attribute |
Required |
Description |
Values |
home |
Yes |
The total score of the home team |
Integer |
away |
Yes |
The total score of the away team |
Integer |
<goal>
| Property |
Value |
| Nesting |
match/liveData/goal |
| Description |
Root element of the fields related to the goal. |
| Attribute |
Required |
Description |
Values |
type |
Yes |
The type of prediction that describes the goal |
String |
scorerId |
Yes |
Unique ID (UUID) of the scorer |
String (Alphanumeric-UUID) |
scorerName |
Yes |
The name of the player who scored the goal |
String |
assistPlayerId |
No |
Unique ID (UUID) of the player who assisted the goal. Attribute not present if there was no assist. |
String (Alphanumeric-UUID) |
assistPlayerName |
No |
The name of the player who assisted the goal. Attribute not present if there was no assist. |
String |
optaEventId |
Yes |
The Opta ID of the event |
String |
homeScore |
Yes |
The score scored by the home team. |
Integer |
awayScore |
Yes |
The score scored by the away team. |
Integer |
contestantId |
Yes |
Unique ID (UUID) of the scorer's team |
String (Alphanumeric - UUID) |
periodId |
Conditional |
The ID of the match period in which the goal was scored - one of the following: 1 | 2 | 3 | 4 |
Integer |
timeMin |
Yes |
The minute of the match in which the goal was scored |
Integer |
timeMinSec |
Yes |
The second attributed to the minute in the match in which the goal was scored |
String |
lastUpdated |
Yes |
The UTC date and time (timestamp) of when the event information/record was last updated |
Date/Time - in the format: YYYY-MM-DDThh:mm:ssZ |
timestamp |
No |
The UTC date and time (timestamp) of when the event updated. |
Date/Time - in the format: YYYY-MM-DDThh:mm:ssZ |
<card>
| Property |
Value |
| Nesting |
match/liveData/card |
| Description |
Root element of the fields relating to card in the given match. |
| Attribute |
Required |
Description |
Values |
type |
Yes |
The type of the card - one of the following:YC(yellow) |Y2C(second yellow) |RC(red) |
String |
playerId |
Yes |
Unique (UUID) of the player who received the card |
String (Alphanumeric - UUID) |
playerName |
Yes |
The name of the player who received the card |
String |
optaEventId |
Yes |
The Opta ID of the event |
Integer |
cardReason |
Conditional |
The reason that the card was awarded - this depends on the type/colour of the card: Yellow Card type="YC" reasons (possible values): Foul | Persistent infringement | Hand Ball | Dangerous play | Time wasting | Argument | Dissent | Simulation | Excessive celebration | Encroachment | Leaving field of play | Entering field of play | Off the ball foul | Not Retreating | Entering referee review area | Excessive usage of review signal | Other Reason Red Card type="RC" reasons (possible values): Violent conduct | Spitting | Professional Foul Last Player | Professional Foul Handball | Serious Foul | Foul and abusive language | Entering video operations room |
String |
contestantId |
Yes |
Unique ID (UUID) of the player's team |
String (Alphanumeric - UUID) |
periodId |
Conditional |
Match period in which the player received the card |
Integer - one of the following: 1 | 2 | 3 | 4 |
timeMin |
Yes |
Minute of the match associated with the card event. |
Integer |
timeMinSec |
Yes |
Second attributed to the minute of the match associated with the card event. |
String |
lastUpdated |
Yes |
The UTC date and time (timestamp) of when the card event information/record was last updated |
Date/Time - in the format: YYYY-MM-DDThh:mm:ssZ |
timestamp |
No |
The UTC date and time (timestamp) of when the card event information/record was updated |
Date/Time - in the format: YYYY-MM-DDThh:mm:ssZ |
<substitute>
| Property |
Value |
| Nesting |
match/liveData/substitute |
| Description |
Root element of the fields relating to substitute, in the given match. |
| Attribute |
Required |
Description |
Values |
playerOnId |
Yes |
Unique ID (UUID) of the player being substituted on |
String (Alphanumeric - UUID) |
playerOnName |
Yes |
The match name of player being substituted on |
String |
playerOffId |
Yes |
Unique ID (UUID) of the player being substituted off |
String (Alphanumeric - UUID) |
playerOffName |
Yes |
The match name of player being substituted off |
String |
subReason |
Yes |
The reason that the substitution was made - one of the following:Tactical | Injury |
String |
contestantId |
Yes |
Unique ID (UUID) of the contestant. |
String (Alphanumeric - UUID) |
periodId |
Conditional |
The period ID of the match in which the substitution was made |
Integer - one of the following: 1 | 2 | 3 | 4 |
timeMin |
Yes |
Minute of the match when the substitute player enters. |
Integer |
timeMinSec |
Yes |
Second attributed to the minute when the substitute player enters. |
String |
lastUpdated |
Yes |
The UTC date and time (timestamp) of when the substitution event information/record was last updated |
Date/Time - in the format: YYYY-MM-DDThh:mm:ssZ |
timestamp |
No |
The UTC date and time (timestamp) of when the substitution was made |
Date/Time - in the format: YYYY-MM-DDThh:mm:ssZ |
<VAR>
| Property |
Value |
| Nesting |
match/liveData/VAR |
| Description |
Added in June 2019 update: Root element of the fields relating to all VAR (Video Assistant Referee) events/reviews. |
| Note |
Only returned if the call includes the parameter-value live=yes and data is available. It will only appear in a game where there has been a VAR review and will list all VAR events in a game, the player and team involved, the type of event reviewed, whether the original decision was upheld, and the outcome of the review. This list will update during a game as more events are reviewed. If no data is available (for example, if the fixture is scheduled but is not playing or has not been played) then the liveData element may be empty or some sub-elements will not be returned. However, when new information is available the feed will be updated - see our polling frequency recommendations for more information. |
| Attribute |
Required |
Description |
Values |
type |
Conditional |
The type of event/decision that requires a VAR review - one of the following: Goal awarded | Goal not awarded | Penalty awarded | Penalty not awarded | Red card given | Card upgrade | Mistaken Identity | Other • Appears in the feed, alongside other attributes related to a VAR review. • To see a full explanation of the possible combination of VAR events, Referee decisions, and Outcomes, see: How are VAR events reported? |
String |
decision |
Yes |
The decision that the referee has made about the event, following the VAR review. |
String - one of the following: Confirmed | Cancelled |
outcome |
Conditional |
The outcome of the event, in relation to the original decision and following the VAR review and decision - one of the following: Goal | No goal | Penalty | No penalty | Red card awarded | No red card | Ref cautions/sends off different player | Player originally cautioned confirmed |
String |
playerId |
Yes |
Unique ID (UUID) of the player involved in an event that requires a Video Assistant Referee (VAR) review. |
String (Alphanumeric - UUID) |
playerName |
Yes |
Name of the player involved in an event that requires a Video Assistant Referee (VAR) review. |
String |
optaEventId |
Yes |
The Opta ID of the event |
Integer |
contestantId |
Yes |
Unique ID (UUID) of a contestant associated with a player involved in an event that requires a Video Assistant Referee (VAR) review. |
String (Alphanumeric - UUID) |
periodId |
Conditional |
The ID of the match period in which the event was subject to the VAR review |
Integer - one of the following: 1 | 2 | 3 | 4 | 5 |
timeMin |
Yes |
The minute of the match in which the event was subject to the VAR review |
Integer |
timeMinSec |
Yes |
The second attributed to the minute in the match in which the event was subject to the VAR review |
String |
lastUpdated |
Yes |
The UTC date and time (timestamp) of when the event information/record was last updated |
Date/Time - in the format: YYYY-MM-DDThh:mm:ssZ |
timestamp |
No |
The UTC date and time (timestamp) of when the event information/record updated. |
Date/Time - in the format: YYYY-MM-DDThh:mm:ssZ |
`<line
Up>`
| Property |
Value |
| Nesting |
match/liveData/lineUp |
| Description |
Root element of the fields related to the lineUp of the players in the given team. |
| Attribute |
Required |
Description |
Values |
contestantId |
Yes |
Unique ID (UUID) of the contestant |
String (Alphanumeric - UUID) |
formationUsed |
No |
The formation type used by that team |
String |
`<team
Official>`
| Property |
Value |
| Nesting |
match/liveData/lineUp/teamOfficial |
| Description |
Root element of the fields related to the teamOfficial. Includes multiple team officials in a team's lineup. |
| Attribute |
Required |
Description |
Values |
id |
Yes |
Unique ID (UUID) of the team official |
String (Alphanumeric - UUID) |
firstName |
Yes |
The first name of the team official |
String |
lastName |
Yes |
The last name (second name) of the team official. Note: This replaced secondName |
String |
shortFirstName |
No |
The short first name of the team official |
String |
shortLastName |
No |
The short last name of the team official |
String |
knownName |
No |
The known name of the team official |
String |
type |
Yes |
The type of the team official - eg 'manager' |
String |
`<pre
MatchPredictions>`
| Property |
Value |
| Nesting |
match/liveData/lineUp/preMatchPredictions |
| Description |
Root element of the fields related to the pre match predictions. |
| Attribute |
Required |
Description |
Values |
| None |
No |
This element has no documented attributes. |
N/A |
<players> under `<pre
MatchPredictions>`
| Property |
Value |
| Nesting |
match/liveData/lineUp/preMatchPredictions/players |
| Description |
Root element of the fields related to the players. |
| Attribute |
Required |
Description |
Values |
| None |
No |
This element has no documented attributes. |
N/A |
<player> under `<pre
MatchPredictions>`
| Property |
Value |
| Nesting |
match/liveData/lineUp/preMatchPredictions/players/player |
| Description |
Root element of the fields related to the player. |
| Attribute |
Required |
Description |
Values |
playerId |
Yes |
Unique ID (UUID) of the player |
String (Alphanumeric - UUID) |
firstName |
Yes |
The first name of the player |
String |
lastName |
Yes |
The last name of the player |
String |
birthName |
No |
The birth name of the person/player |
String |
matchName |
No |
Match name of the player. Note: This node may not be returned for every player. If it does exist, you may wish to use it instead, and ignore the firstName and lastName nodes. For example, 'Neymar' will have a known name. |
String |
shirtNumber |
Yes |
The shirt number of the player |
Integer |
position |
Yes |
The position of the player in the starting lineup - one of the following: Goalkeeper | Wing Back | Defender | Defensive Midfielder | Attacking Midfielder | Midfielder | Striker | Substitute |
String |
positionSide |
No |
Player position side on the pitch - one of the following: Left, Right, Centre, Left/Centre, Centre/Right |
String |
formationPlace |
Yes |
The formation place of the player. |
Integer |
isInjured |
Yes |
The injury status of the player. Possible values: 0 | 1 |
Integer |
<team> under `<pre
MatchPredictions>`
| Property |
Value |
| Nesting |
match/liveData/lineUp/preMatchPredictions/team |
| Description |
Root element of the fields related to the team. |
| Attribute |
Required |
Description |
Values |
| None |
No |
This element has no documented attributes. |
N/A |
<stat> under pre-match <team>
| Property |
Value |
| Nesting |
match/liveData/lineUp/preMatchPredictions/team/stat |
| Description |
Root element of the fields related to the statistics of the team. |
| Attribute |
Required |
Description |
Values |
target |
Yes |
The target score of the team |
String |
seasonAvg |
Yes |
The season average of the team. |
Integer |
type |
Yes |
The type of the statistics. |
String |
`<live
Predictions>`
| Property |
Value |
| Nesting |
match/liveData/lineUp/livePredictions |
| Description |
Root element of the fields related to live predictions. |
| Attribute |
Required |
Description |
Values |
| None |
No |
This element has no documented attributes. |
N/A |
`<live
Prediction>`
| Property |
Value |
| Nesting |
match/liveData/lineUp/livePredictions/livePrediction |
| Description |
Root element of the fields related to live prediction. |
| Note |
Only returned if data is available. If no data is currently available then the liveData element may be empty or some sub-elements will not be returned. However, when new information is available the feed will be updated - see our polling frequency recommendations for more information. |
| Attribute |
Required |
Description |
Values |
timeMin |
Yes |
The minute taken. |
Integer |
timeSec |
Yes |
The minute taken in seconds. |
Integer |
periodId |
Yes |
The current match period. |
Integer |
<players> under `<live
Prediction>`
| Property |
Value |
| Nesting |
match/liveData/lineUp/livePredictions/livePrediction/players |
| Description |
Root element of the fields related to the players. |
| Attribute |
Required |
Description |
Values |
| None |
No |
This element has no documented attributes. |
N/A |
<player> under `<live
Prediction>`
| Property |
Value |
| Nesting |
match/liveData/lineUp/livePredictions/livePrediction/players/player |
| Description |
Root element of the fields related to the player. |
| Attribute |
Required |
Description |
Values |
playerId |
Yes |
Unique ID (UUID) of the player |
String (Alphanumeric - UUID) |
firstName |
Yes |
First name of the player. |
String |
lastName |
Yes |
Last name of the player. |
String |
birthName |
No |
The birth name of the person/player |
String |
matchName |
No |
Match name of the player. This node may not be returned for every player; when present, it can be used instead of firstName and lastName. |
String |
shirtNumber |
Yes |
The shirt number of the player |
Integer |
position |
Yes |
The position of the player in the starting lineup - one of the following: Goalkeeper | Wing Back | Defender | Defensive Midfielder | Attacking Midfielder | Midfielder | Striker | Substitute |
String |
positionSide |
No |
Player position side on the pitch - one of the following: Left, Right, Centre, Left/Centre, Centre/Right |
String |
formationPlace |
Yes |
The formation place of the player. |
Integer |
<stat> under live-prediction <player>
| Property |
Value |
| Nesting |
match/liveData/lineUp/livePredictions/livePrediction/players/player/stat |
| Description |
Root element of the fields related to the player statistics. |
| Attribute |
Required |
Description |
Values |
type |
Yes |
The type of the statistics. |
String |
target |
Yes |
The target score of the player. |
String |
seasonAvg |
Yes |
The season average of the player. |
String |
<team> under `<live
Prediction>`
| Property |
Value |
| Nesting |
match/liveData/lineUp/livePredictions/livePrediction/team |
| Description |
Root element of the fields related to the team. |
| Attribute |
Required |
Description |
Values |
| None |
No |
This element has no documented attributes. |
N/A |
<stat> under live-prediction <team>
| Property |
Value |
| Nesting |
match/liveData/lineUp/livePredictions/livePrediction/team/stat |
| Description |
Root element of the fields related to the team statistics. |
| Attribute |
Required |
Description |
Values |
type |
Yes |
The type of the statistics |
String |
target |
Yes |
Target score of the team. |
String |
seasonAvg |
Yes |
Season average of the team. |
String |
`<match
DetailsExtra>`
| Property |
Value |
| Nesting |
match/liveData/matchDetailsExtra |
| Description |
Root element of the fields related to the match details. |
| Attribute |
Required |
Description |
Values |
| None |
No |
This element has no documented attributes. |
N/A |
<attendance>
| Property |
Value |
| Nesting |
match/liveData/matchDetailsExtra/attendance |
| Description |
Root element of the fields related to attendance. Value: Integer, the attendance of the match |
| Attribute |
Required |
Description |
Values |
| None |
No |
This element has no documented attributes. |
N/A |
`<match
Officials>`
| Property |
Value |
| Nesting |
match/liveData/matchDetailsExtra/matchOfficials |
| Description |
Root element of the fields related to the match officials. |
| Attribute |
Required |
Description |
Values |
| None |
No |
This element has no documented attributes. |
N/A |
`<match
Official>`
| Property |
Value |
| Nesting |
match/liveData/matchDetailsExtra/matchOfficials/matchOfficial |
| Description |
This element is optional (it may not always be returned in the feed - for example if the fixture is scheduled but is not playing or has not been played) then the liveData element may be empty or some sub-elements will not be returned. |
| Attribute |
Required |
Description |
Values |
id |
Yes |
Unique ID (UUID) of the match official. |
String (Alphanumeric - UUID) |
type |
Yes |
The type of match official - example: Main | Assistant referee 1 | Assistant referee 2 | Fourth official | Video Assistant Referee |Assistant VAR Official | |
String |
firstName |
Yes |
The first name of the match official. |
String |
lastName |
Yes |
The last name of the match official. |
String |
