Stats Perform logo

Sports Data API - Soccer - Match Events Possession Value Feed (MA32)

Overview

The Soccer Match Events Possession Value feed provides Possession Values mapped to individual events in a queried soccer match.

The feed combines match metadata, competition metadata, event metadata, team details, player details, event coordinates, timestamps, and event-level Possession Value fields. Possession Value measures the likelihood that the team in possession will score a goal in the next 10 seconds.

Included Data Category Description
Match metadata Fixture identifiers, dates, times, coverage level, period configuration, attendance context, VAR availability, and last-updated timestamp.
Competition metadata Sport, ruleset, competition, country, tournament calendar, stage, and optional series data.
Contestant metadata Home and away team identifiers, names, short names, official names, codes, positions, and country.
Venue metadata Venue identifier, neutrality flag, legacy IDs, long name, short name, latitude, and longitude.
Live match state Period, match status, match clock, winner, aggregate tie metadata, match length, and player/team-of-the-match metadata.
Scores Half-time, full-time, extra-time, penalty, total, and Tier 13 unconfirmed score states.
Event data Event IDs, event type IDs, period, match time, contestant/player identifiers, event outcome, assist/key-pass flags, pitch coordinates, and timestamps.
Event Possession Value pvValue and pvAdded mapped to each event.
External reference https://www.theanalyst.com/eu/2021/03/what-is-possession-value/

Problem Statement & Use Cases

This API solves the business problem of assigning possession-value impact to the specific events that occur during a soccer match. Instead of evaluating only aggregate team or player totals, the feed maps Possession Value directly to event records, allowing systems to identify which actions increased or decreased the scoring probability of the team in possession.

Use Case Description
Event-level action valuation Attach pvValue and pvAdded to passes, carries, shots, crosses, recoveries, fouls, and other event types for granular action analysis.
Live match analytics dashboards Power real-time visualizations showing which events are changing attacking threat during a live fixture.
Player and team contribution models Use event-level Possession Value as a feature for player impact, team style, and possession-quality models.
Broadcast and editorial storytelling Highlight high-value actions, key passages of play, and momentum-changing events beyond goals and shots.

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.

Polling Frequency

Contact a Stats Perform representative for confirmed rate limits or additional polling guidance.

Update Condition Recommended Polling Frequency
Match queried is live Once per minute.

Fixture Identifier Requirements

The /matcheventspossessionvalues feed must be queried by a fixture or match UUID.

Requirement Detail
Fixture identifier Query by fixture UUID in the path or by fx query parameter.
UUID discovery Use the Tournament Calendar (OT2) or Fixtures and Results (MA1) feeds to retrieve fixture metadata, fixture UUIDs, linked contestants, competition, tournament calendar, and related entities.
Legacy ID support The fx parameter can filter by legacy IDs.
Legacy ID limitation Only one legacy ID is supported. Do not pass multiple legacy IDs in a comma-separated list.

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 or path parameter.
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 _lcl.
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.

Opta Naming Locale Constraint

Do not supply both _lcl with a locale/language code and _lcl=en-op in the same call.

Constraint Requirement Error Behavior
Opta English naming Use _lcl=en-op to return assets with Opta namings in English instead of Opta Core namings. Supported with other valid parameters and values.
Duplicate _lcl parameter Do not combine _lcl=en-op with another _lcl locale/language code in the same request. The feed returns error code 10203 for ambiguous or invalid request parameters caused by duplicated _lcl.

Endpoints

Base URL

https://api.statsperform.com

Feed Resource

/sdapi/v1/soccerdata/matcheventspossessionvalues

Get Match Events Possession Value by Fixture UUID

GET /sdapi/v1/soccerdata/matcheventspossessionvalues/{fixtureUuid}?{queryParameters}

GET https://api.statsperform.com/sdapi/v1/soccerdata/matcheventspossessionvalues/{fixtureUuid}?_fmt={dataFormat}
Usage Feed
Get Match Events Possession Value by fixture UUID using the path parameter method. /sdapi/v1/soccerdata/matcheventspossessionvalues/{fixtureUUID}?{queryParameters}

Get Match Events Possession Value by fx Query Parameter

GET /sdapi/v1/soccerdata/matcheventspossessionvalues?fx={fixtureUuid}&{queryParameters}

GET https://api.statsperform.com/sdapi/v1/soccerdata/matcheventspossessionvalues?_fmt={dataFormat}&fx={fixtureUuid}
Usage Feed
Get Match Events Possession Value by fixture using the fx query parameter. /sdapi/v1/soccerdata/matcheventspossessionvalues?fx={fixtureUUID}&{queryParameters}

Get Match Events Possession Value by Event Type

GET /sdapi/v1/soccerdata/matcheventspossessionvalues/{fixtureUuid}?{queryParameters}&type={typeId}

GET https://api.statsperform.com/sdapi/v1/soccerdata/matcheventspossessionvalues/{fixtureUuid}?_fmt={dataFormat}&ctst={contestantUuid}&prsn={personUuid}&type={typeId}

GET https://api.statsperform.com/sdapi/v1/soccerdata/matcheventspossessionvalues/{fixtureUuid}?_fmt={dataFormat}&ctst={contestantUuid}&prsn={personUuid}&type={typeId},{typeId},{typeId}
Usage Feed
Get Match Events Possession Value for one or more event types in a fixture. /sdapi/v1/soccerdata/matcheventspossessionvalues/{fixtureUUID}?{queryParameters}&type={type value}

Query Parameters

This feed uses Global query parameters and the feed-specific parameters listed below.

Query /matcheventspossessionvalues by a fixture or match UUID. The fx parameter supports a single legacy ID only; comma-separated legacy ID lists are not supported.

Global Query Parameters

Parameter Required Description Values / Format Notes
_fmt Yes in examples Response data format. {dataFormat}, such as xml, json, or jsonp. Global query parameter.
_clbk Conditional JSONP callback function name. Fixed callback function name. Required when _fmt=jsonp.
_lcl=en-op No Returns assets with Opta namings in English instead of Opta Core namings. Fixed parameter-value _lcl=en-op. Cannot be combined with another _lcl locale/language code.

Feed-Specific Query Parameters

Parameter Location Required Description Accepted Values / Format Example Request
fixtureUuid Path Yes when using the path endpoint Gets Match Events Possession Value by the specified fixture UUID. Pass the fixture UUID directly in the request URL as the asset or resource ID. Fixture UUID. GET https://api.statsperform.com/sdapi/v1/soccerdata/matcheventspossessionvalues/{fixtureUuid}?_fmt={dataFormat}
fx Query Yes when not using the path endpoint Gets Match Events Possession Value by the specified fixture UUID using the query parameter method. Also supports legacy ID filtering. One fixture UUID or one supported legacy ID. GET https://api.statsperform.com/sdapi/v1/soccerdata/matcheventspossessionvalues?_fmt={dataFormat}&fx={fixtureUuid}
type Query No Gets Match Events Possession Value only for specific event type IDs in the fixture, such as shots, goals, and crosses. One typeId or a comma-separated list of up to 20 typeId values. GET https://api.statsperform.com/sdapi/v1/soccerdata/matcheventspossessionvalues/{fixtureUuid}?_fmt={dataFormat}&ctst={contestantUuid}&prsn={personUuid}&type={typeId},{typeId},{typeId}

Event Type Filter Constraints

Constraint Requirement
Single event type Use type={typeId}.
Multiple event types Use a comma-separated list: type={typeId},{typeId},{typeId}.
Maximum event types Up to 20 typeId values.
Event type source Use the event type ID reference in the Output Schema section to map typeId values to event names.

Opta Naming Query Parameter

GET https://api.statsperform.com/sdapi/v1/soccerdata/matcheventspossessionvalues/{fixtureUuid}?_fmt={dataFormat}&_lcl=en-op&{queryParameters}
Parameter Description Constraint
_lcl=en-op Returns assets with Opta namings in English instead of Opta Core namings. Do not combine with another _lcl locale/language code.

Output Schema

The feed response fields are documented using XML element names. JSON and JSONP responses contain similar fields, but XML-only wrapper elements are omitted or represented differently.

The root element can be matchEventsPossessionValues in XML. It is not present in JSON/JSONP, where the root element is matchInfo.

If the match has not yet been played, not all attributes are present and placeholder values may be returned. Scores, winner, contestant name, position, and contestant ID may be unknown or omitted until the feed is updated.

If no live data is available, such as when the fixture is scheduled but not playing or not yet played, an empty liveData element can be returned and some sub-elements may be omitted.

`<match

EventsPossessionValues>`

Property Value
Format / Scope (XML only)
Nesting matchEventsPossessionValues
Description Root element of the related fields for Match Events Possession Value (XML only)
Note Not present in JSON/JSONP feed response, where the root element is matchInfo
Attributes No attributes.

`<match

Info>`

Property Value
Nesting matchEventsPossessionValues/matchInfo
Description Required. Root element of the related fields for the match information (matchInfo)
Attribute Required Description Values
id Yes Required. Unique ID (UUID) of the fixture/match String (Alphanumeric - UUID)
ocId No Optional. Unique Opta Core match ID. Returned only if the feed is queried by Opta Core legacy ID. Empty string if the ID does not exist. String
opId No Optional. Unique Opta match ID. Returned only if the feed is queried by Opta legacy ID. Empty string if the ID does not exist. String
coverageLevel No Coverage level - this information is useful for understanding the data collection coverage level (also known as 'Tier') our analysts adhere to, and subsequently what data is then available to you through the feeds as an end user. String (Numeric)
date Yes Required. The date (UTC) of the fixture/match Date - in the format: YYYY-MM-DDZ
time No Optional. The start time (UTC) of the fixture/match
Note: This attribute-value may not be present until we have received confirmation of the time. Once received, we will update the feed.		 String - in the format: hh:mm:ssZ
localDate Yes Required. The date (local) of the fixture/match Date - in the format: YYYY-MM-DD
localTime No Optional. The start time (local) of the fixture/match String - in the format: hh:mm:ss
week No Optional. The week in which the match is taking place String
attendanceInfoId No Optional. The attendance information ID - for example:
• 1 = match is played 'Behind Closed Doors' which should mean that people will not attend the match at the venue
• 2 = match is played with a 'Limited Audience'		 String
attendanceInfo No Optional. The additional attendance information - for example: Behind Closed Doors or Limited Audience String
numberOfPeriods No Optional. The number of periods that will be played. For example, a regular soccer match will have two periods. Integer
periodLength No Optional. The duration of a period. For example, the duration of a period in a regular soccer match is 45 minutes. Integer
overtimeLength No Optional. The length of the overtime if the match goes beyond the regular time. Integer
varEnabled No Optional. Indicates whether the fixture has VAR related data.
Possible values: 0 | 1 | {attribute not present}.
0 - VAR info not collected.
1 - VAR info collected.
{attribute not present} - unknown.		 String
lastUpdated Yes Required. The UTC date and time (timestamp) of when the fixture information/record was last updated Date/Time - in the format: YYYY-MM-DDThh:mm:ssZ

<description>

Property Value
Nesting matchEventsPossessionValues/matchInfo/description
Description Optional. Description of the match. Value: string giving the description - for example, the contestant names
Attributes No attributes.

<sport>

Property Value
Nesting matchEventsPossessionValues/matchInfo/sport
Description Required. Root element of the related fields for the sport. Value (XML only): string giving the sport name (for example: Soccer)
Attribute Required Description Values
id Yes Required. Unique ID (UUID) of the sport String (Alphanumeric - UUID)
name (JSON only) Yes Required. Name of the sport String

<ruleset>

Property Value
Nesting matchEventsPossessionValues/matchInfo/ruleset
Description Required. Root element of the fields related to ruleset. Value (XML only): String giving the ruleset name
Attribute Required Description Values
id Yes Required. Unique ID (UUID) of the ruleset String (Alphanumeric - UUID)
name (JSON only) Yes Required. Name of the ruleset String

<competition>

Property Value
Nesting matchEventsPossessionValues/matchInfo/competition
Description Required. Root element of the fields related to the competition
Attribute Required Description Values
id Yes Required. Unique ID (UUID) of the competition String (Alphanumeric - UUID)
ocId No Optional. Unique Opta Core competition ID. Returned only if the feed is queried by Opta Core legacy ID; the attribute is not present otherwise. Empty string if no such value exists. String
opId No Optional. Unique Opta competition ID. Returned only if the feed is queried by Opta legacy ID; the attribute is not present otherwise. Empty string if no such value exists. String
name Yes Required. The name of the competition String
knownName Yes Required. The known name of the competition String
sponsorName Yes Required. The name of the sponsor of a competition String
competitionCode Yes Required. The short three-digit competition code String
competitionFormat Yes Required. The format of the competition - one of the following values: Domestic league | Domestic cup | Domestic super cup | International cup | International super cup String

<country> (competition country)

Property Value
Nesting matchEventsPossessionValues/matchInfo/competition/country
Description Required. 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 Required. Unique ID (UUID) of the country that the competition is based in String (Alphanumeric - UUID)
name (JSON only) Yes Required. Name of the country String

`<tournament

Calendar>`

Property Value
Nesting matchEventsPossessionValues/matchInfo/tournamentCalendar
Description Required. 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 Required. Unique ID (UUID) of the tournament calendar String (Alphanumeric - UUID)
ocId No Optional. Unique Opta Core tournament calendar ID. Returned only if the feed is queried by Opta Core legacy ID; the attribute is not present otherwise. Empty string if no such value exists. String
opId No Optional. Unique Opta tournament calendar ID. Returned only if the feed is queried by Opta legacy ID; the attribute is not present otherwise. Empty string if no such value exists. String
startDate Yes Required. The start date (UTC) of the tournament calendar Date - in the format: YYYY-MM-DDZ
endDate Yes Required. The end date (UTC) of the tournament calendar Date - in the format: YYYY-MM-DDZ
name (JSON only) Yes Required. Name of the tournament calendar String

<stage>

Property Value
Nesting matchEventsPossessionValues/matchInfo/stage
Description Required. Root element of the fields related to the stage. Value (XML only): String giving the stage name
Attribute Required Description Values
id Yes Required. Unique ID (UUID) of the stage String (Alphanumeric - UUID)
ocId No Optional. Unique Opta Core stage ID. Returned only if the feed is queried by Opta Core legacy ID; the attribute is not present otherwise. Empty string if no such value exists. String
opId No Optional. Unique Opta stage ID. Returned only if the feed is queried by Opta legacy ID; the attribute is not present otherwise. Empty string if no such value exists. String
formatId Yes Required. 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 Required. The start date (UTC) of the stage Date - in the format: YYYY-MM-DDZ
endDate Yes Required. The end date (UTC) of the stage Date - in the format: YYYY-MM-DDZ
name (JSON only) Yes Required. Name of the stage String

<series>

Property Value
Nesting matchEventsPossessionValues/matchInfo/series
Description Optional. Root element of the fields related to the series - this element is optional (it may not always be returned in the feed). Value (XML only): String giving the series name
Attribute Required Description Values
id Yes Required. Unique ID (UUID) of the series String (Alphanumeric - UUID)
ocId No Optional. Unique Opta Core series ID. Returned only if the feed is queried by Opta Core legacy ID. Empty string if the ID does not exist. String
opId No Optional. Unique Opta series ID. Returned only if the feed is queried by Opta legacy ID. Empty string if the ID does not exist. String
horizontal No Optional. The order to display fixtures and standings for groups with the same vertical value. String
formatId Yes Required. Unique ID related to the series format of the competition String (Alphanumeric - UUID)
name (JSON only) Yes Required. Name of the series String

<contestants>

Property Value
Format / Scope (XML only)
Nesting matchEventsPossessionValues/matchInfo/contestants
Description Optional. Root element of the fields related to the contestants (XML only) - this element is optional (it may not always be returned in the feed)
Note Not present in JSON/JSONP feed response, where the individual contestant elements are returned instead
Attributes No attributes.

<contestant> (match contestant)

Property Value
Nesting matchEventsPossessionValues/matchInfo/contestants/contestant
Description Optional. 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 Required. Unique ID (UUID) of the contestant String (Alphanumeric - UUID)
ocId No Optional. Unique Opta Core contestant ID. Returned only if the feed is queried by Opta Core legacy ID. Empty string if the ID does not exist. String
opId No Optional. Unique Opta contestant ID. Returned only if the feed is queried by Opta legacy ID. Empty string if the ID does not exist. String
name Yes Required. The name of the contestant String
shortName No Optional. The short name commonly used to refer to the contestant String
officialName Yes Required. The official name of the contestant String
code No Optional. The 3-character code used for the name of the contestant - it is often used on TV scoreboards String
position Yes Required. 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> (contestant country)

Property Value
Nesting matchEventsPossessionValues/matchInfo/contestants/contestant/country
Description Optional. 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 Required. Unique ID (UUID) of the country the contestant is from String (Alphanumeric - UUID)
name (JSON only) Yes Required. Name of the country String

<venue>

Property Value
Nesting matchEventsPossessionValues/matchInfo/venue
Description Optional. 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 Required. Unique ID (UUID) of the venue String (Alphanumeric - UUID)
neutral Yes Required. 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
ocId No Optional. Unique Opta Core venue ID. Returned only if the feed is queried by Opta Core legacy ID; the attribute is not present otherwise. Empty string if no such value exists. String
opId No Optional. Unique Opta venue ID. Returned only if the feed is queried by Opta legacy ID; the attribute is not present otherwise. Empty string if no such value exists. String
longName Yes Required. The long/extended name of the venue String
latitude No Optional. The latitude coordinates for the location of the venue String
longitude No Optional. The longitude coordinates for the location of the venue String
shortName (JSON only) Yes Required. The short name of the venue String

`<live

Data>`

Property Value
Nesting matchEventsPossessionValues/liveData
Description Required. 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.
Attributes No attributes.

`<match

Details>`

Property Value
Nesting matchEventsPossessionValues/liveData/matchDetails
Description Required. Root element of the fields related to the match details
Attribute Required Description Values
periodId Yes Required. 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 Required. The status of the match - one of the following: Fixture | Playing | Played | Cancelled | Postponed | Suspended | Awarded
• Fixture - The match is scheduled and yet to start
• Playing - The game is live
• Cancelled - The game is cancelled due to some reason
• Postponed - The game is postponed to another date
• Suspended - The match is interrupted in between and suspended. It can be rescheduled to another date in future
• Awarded - The match is awarded to one contestants with an associated result		 String
matchTime No Optional. The current minute of the match. Available only for certain competitions and during the match (when matchStatus="Playing"). Integer
winner No Optional. 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 Optional. The leg of the competition a match is being played in. Integer
aggregateId No Optional. 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 Optional. It contain aggregated IDs for previous rounds of the fixture. (e.g., previousRoundAggregateId1, previousRoundAggregateId2) String
previousMatchIds No Optional. UUID of 'Previous Match' String (Alphanumeric - UUID)
advancementAggregateId No Optional. 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 Optional. 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 Optional. 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 Optional. UUID of 'Team of the Match' String (Alphanumeric - UUID)
playerOfTheMatch No Optional. Name of 'Player of the Match' String
playerOfTheMatchId No Optional. UUID of 'Player of the Match' String (Alphanumeric - UUID)
goalkeeperOfTheMatch No Optional. Name of 'Goal Keeper of the Match String
goalkeeperOfTheMatchId No Optional. UUID of 'Goal Keeper of the Match' String (Alphanumeric - UUID)

<periods>

Property Value
Format / Scope (XML only)
Nesting matchEventsPossessionValues/liveData/matchDetails/periods
Description Optional. 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.
Attributes No attributes.

<period>

Property Value
Nesting matchEventsPossessionValues/liveData/matchDetails/periods/period
Description Optional. 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 Required. The match period ID - one of the following: 1 | 2 | 3 | 4 Integer
start Yes Required. The start date and time of the period (UTC) Date/Time - in the format: YYYY-MM-DDThh:mm:ssZ
end Yes Required. The end date and time of the period (UTC) Date/Time - in the format: YYYY-MM-DDThh:mm:ssZ
lengthMin Yes Required. The number of total minutes in the period (includes stoppage time) Integer
lengthSec Yes Required. The number of seconds in addition to the total minutes in the period (includes stoppage time) Integer
announcedInjuryTime Yes Required. Injury time in seconds Integer

<suspensions>

Property Value
Nesting matchEventsPossessionValues/liveData/matchDetails/periods/period/suspensions
Description Optional. Root element of the fields related to suspensions in a period of a match (XML only)
Attributes No attributes.

<suspension>

Property Value
Nesting matchEventsPossessionValues/liveData/matchDetails/periods/period/
suspensions/suspension
Description Optional. Root element of the fields related to suspension in a period of a match.
This element is optional (it may not always be returned in the feed).
Attribute Required Description Values
start No The start date and time of the suspension period (UTC) Date/Time in the format: YYYY-MM-DDThh:mm:ssZ
end No The end date and time of the period (UTC) Date/Time in the format: YYYY-MM-DDThh:mm:ssZ
reason No Optional. Providing the reason for a game suspension - one of the following:
clock affecting
early end		 String

<scores>

Property Value
Nesting matchEventsPossessionValues/liveData/matchDetails/scores
Description Optional. 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'.
Attributes No attributes.

<ht> (half-time score)

Property Value
Nesting matchEventsPossessionValues/liveData/matchDetails/scores/ht
Description Optional. 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 Required. The half-time score of the home team Integer
away Yes Required. The half-time score of the away team Integer

<ft> (full-time score)

Property Value
Nesting matchEventsPossessionValues/liveData/matchDetails/scores/ft
Description Optional. 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 Required. The full-time score of the home team Integer
away Yes Required . The full-time score of the away team Integer

<et> (extra-time score)

Property Value
Nesting matchEventsPossessionValues/liveData/matchDetails/scores/et
Description Optional. Root element of the fields related to the extra half scores - this element is optional (it may not always be returned in the feed).
Attribute Required Description Values
home Yes Required. The extra-time score of the home team Integer
away Yes Required. The extra-time score of the away team Integer

<pen> (penalty score)

Property Value
Nesting matchEventsPossessionValues/liveData/matchDetails/scores/pen
Description Optional. Root element of the fields related to the penalty scores - this element is optional (it may not always be returned in the feed).
Attribute Required Description Values
home Yes Required. The penalties score of the home team Integer
away Yes Required. The penalties score of the away team Integer

<total> (total score)

Property Value
Nesting matchEventsPossessionValues/liveData/matchDetails/scores/total
Description Optional. 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 Required. The total score of the home team Integer
away Yes Required. The total score of the away team Integer

`<total

Unconfirmed>`

Property Value
Nesting matchEventsPossessionValues/liveData/matchDetails/scores/totalUnconfirmed
Description Optional. Root element of the fields related to the total unconfirmed goals - this element is optional (it may not always be returned in the feed).
Note This is a temporary element for only Tier 13 matches, designed to offer a quick way to access score updates. It appears at the point our analysts initially collect a goal event, significantly shortening the time you receive score updates.
Once a goal and goal scorer have been collected, the totalUnconfirmed element is created in the node. Once all goal details are entered into the database the "score" element increments by one (1) and 'totalUnconfirmed' is removed.
By triggering goal updates earlier than previously there is an increased risk that once the goal has been logged it will either be disallowed or a goal scorer may have been misidentified. These clarifications can take a number of seconds to become clear and could result in information which is later updated. Ignore this if you only want to use the other 'scores' attributes
Attribute Required Description Values
home Conditional Required - if element is present. The total unconfirmed goals of the home team Integer
away Conditional Required - if element is present. The total unconfirmed goals of the away team Integer

<events>

Property Value
Format / Scope (XML only)
Nesting matchEventsPossessionValues/liveData/events
Description Root element of the related fields for the live Match Events Possession Value (XML only).
Note This element is only named in XML, not in JSON.
JSON/JSONP: This element is not returned for any calls, because all individual events are returned as an array under the event element - each event in the response can be identified by its own id and typeId, and its relevant attributes and values.
XML: This element contains an array of individual events - each event is contained within its own event element.
Attributes No attributes.

<event>

Property Value
Nesting matchEventsPossessionValues/liveData/events/event
Description Required. Match event element which contains information about an individual event that has occured during the match
JSON/JSONP: This element contains an array of individual events - each event in the response can be identified by its own id and typeId, and its relevant attributes and values.
XML: This element represents an individual event - each event can be identified by its own id and typeId.
Attribute Required Description Values
id Yes Required. The unique ID for this event within Opta's entire database of all events in all games Integer
eventId Yes Required. The unique ID for this event instance for the associated contestant (not the entire fixture) within this match. Each contestant is assigned an eventId value for the given event. Use it in conjunction with the contestantId value to uniquely identify the action in a match. The first instance has a value of '1' and it will be incremented with each event for that contestant. Integer
typeId Yes Required. The ID for the type of event, which defines the type of event that has occurred. Integer
periodId Yes Required. 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
timeMin Yes Required. Game time in minutes Integer
timeSec Yes Required. Game time in seconds Integer
contestantId No Optional. Unique ID (UUID) of the team related to the event String (Alphanumeric - UUID)
opContestantId No Optional. The unique Opta ID of the team related to the event String
playerId No Optional. Unique ID (UUID) of the player related to the event String (Alphanumeric - UUID)
opPlayerId No Optional. The unique Opta ID of the player related to the event String
playerName No Optional. The name of the player related to the event String
outcome No Optional. Boolean operator Integer
assist No Optional. This attribute will only appear for an event if this event led directly to a goal Integer
keyPass No Optional. This attribute will only appear for an event if this event led directly to a shot off target, blocked or saved Integer
x Yes Required. X-coordinate - this is the length of the pitch where 0 is always the defensive goal line and 100 is the attacking goal line. This is true for both teams in both halves. All coordinates are always displayed as if both teams are playing left to right. String (example: 73.9)
y Yes Required. Y-coordinate - this is the width of the pitch where the right-hand touch line (nearest the TV camera) is 0 and the left-hand touch line (furthest away) is 100. String (example: 95.1)
timestamp Yes Required. The UTC time/date at which this event was initially entered into Opta's database Date/Time - in the format: YYYY-MM-DDThh:mm:ssZ
lastModified Yes Required. The UTC time/date at which this event was last modified by Opta Date/Time - in the format: YYYY-MM-DDThh:mm:ssZ

`<possession

Value> (event possession value)`

Property Value
Nesting matchEventsPossessionValues/liveData/events/event/possessionValue
Description Optional. Root element of the fields related to the possession value.
Attribute Required Description Values
pvValue No Optional. The possession value on that event String
pvAdded No Optional. The aggregated prediction value on that event String

Event Type ID Reference

Events are delivered as an array under events for XML or JSON. When an event occurs during a match, it is assigned a unique event ID. Each unique event ID has an associated typeId that classifies the general event type.

Event Type ID Event Name Description
1 Pass An attempt by one player to play the ball to a teammate (includes set pieces). outcome: 0 = Unsuccessful pass = pass did not find teammate | 1 = Successful pass
2 Offside Pass A pass attempt where the intended receiving player is called offside. outcome: always set to 1
3 Take On An attempt by one player to dribble past an opponent. outcome: 0 = Unsuccessful - player lost possession or was tackled | 1 = Successful take on
4 Foul Indicates a foul has been committed. The event comes in pairs, with one for the team committing the foul (has outcome = 0) and another for the team fouled (outcome = 1).
5 Out Indicates the ball has gone out of play for a throw-in or goal kick. The event comes in pairs, with one for the team who have put the ball out of play (outcome = 0) and another for the team who will resume the match in possession (outcome = 1).
6 Corner Awarded Indicates the ball has gone out of play for a corner kick. The event comes in pairs, with one for the team who have conceded the corner (outcome = 0) and another for the team who have won the corner (outcome = 1).
7 Tackle A player successfully dispossess an opponent of the ball. outcome = 1: tackling player's team gains possession or the ball goes out of play. outcome = 0: possession remains with the opponent.
8 Interception When a player intercepts any pass event between opposition players and prevents the ball reaching its target. Cannot be a clearance. outcome: always set to 1
10 Save Goalkeeper event; saving a shot on goal. Can also be an outfield player event with qualifierId 94 for blocked shot. outcome: always set to 1
11 Claim Goalkeeper only event; goalkeeper attempts to catch an aerial ball. outcome:
0 = Keeper drops the ball after an attempted catch from a cross. They may then pick up the ball again and retain possession - this would be a separate event.
1 = Keeper catches the cross in one attempt, for example no drop.
12 Clearance Player deliberately attempts to clear away/put the ball out of play without intentionally targeting the ball towards a teammate. outcome: always set to 1
13 Miss A shot which goes/is projected to travel wide or over the goal. outcome: always set to 1
14 Post A shot which directly hits the frame of the goal. outcome: always set to 1
15 Attempt Saved A shot which is saved by the goalkeeper or blocked by an opposition player. The player performing the event is the shooter. outcome: always set to 1
16 Goal All goals. outcome: always set to 1
17 Card A player is given a card by the referee; qualifiers will indicate whether this was a yellow, second yellow or straight red, as well as the reason for the card. outcome: always set to 1
18 Player off Player is substituted off. outcome: always set to 1
19 Player on Player comes on as a substitute. outcome: always set to 1
20 Player retired Player is forced to leave the pitch due to injury and the team have no substitutions left. outcome: always set to 1
21 Player returns Player comes back on the pitch. outcome: always set to 1
22 Player becomes goalkeeper When an outfield player has to replace the goalkeeper. outcome: always set to 1
23 Goalkeeper becomes player Goalkeeper becomes an outfield player. outcome: always set to 1
24 Condition change Change in playing conditions. outcome: always set to 1
25 Official change Referee or linesman is replaced. outcome: always set to 1
27 Start delay Used to signify the start of a stoppage in play, such as a player injured on the field. outcome: always set to 1
28 End delay Used when the stoppage ends and play resumes. outcome: always set to 1
29 Temporary stop Indicates that there has been a temporary stop in play
Note - October 2019: We will update the documention soon to confirm whether this Event Type ID is still used
30 End End of a match period. outcome: always set to 1
31 Picked an orange Note - October 2019: No longer used
32 Start Start of a match period. outcome: always set to 1
34 Team set up The qualifiers on this event show team lineup and formation information. outcome: always set to 1
35 Player changed position Player moved to a different position, but the team formation remained the same. outcome: always set to 1
36 Player changed Jersey number Player is forced to change jersey number; an associated qualifier will show the new number. outcome: always set to 1
37 Collection End Signals that the match is over and data collection has been completed. outcome: always set to 1
38 Temp Goal Goal has occurred but it is pending additional detail qualifiers from Opta. Will change to event typeId 16. outcome: always set to 1
39 Temp Attempt Shot on goal has occurred but is pending additional detail qualifiers from Opta. Will change to event typeId 15. outcome: always set to 1
40 Formation change Team alters its formation. outcome: always set to 1
41 Punch Goalkeeper only event; goalkeeper punches the ball.
outcome = 0 - the punch lands at an opposition player
outcome = 1 - the punch either lands at the goalkeeper's own team or goes out of play
42 Good skill A player shows a good piece of skill on the ball, such as a step over or turn on the ball. outcome: always set to 1
43 Deleted event Event has been deleted - the event will remain as it was originally with the same event ID but will be present with the event typeId changed to 43. outcome: always set to 1
44 Aerial Two players from opposing teams contest an aerial ball; these events come in pairs, one for each player, with the outcome indicating the success/failure of the aerial duel.
outcome = 0 - Player lost aerial duel
outcome = 1 - Player won aerial duel
45 Challenge A player unsuccessfully attempts to tackle an opponent, making no contact with the ball as the opponent dribbles past them.
outcome: always set to 0 - a challenge by definition is unsuccessful and the player does not win the ball (winning the ball = would be a tackle, eg typeId 7).
46 Postponed
47 Rescinded card This can occur post match if the referee rescinds a card they have awarded. outcome: always set to 1
49 Ball recovery A player gathers a loose ball and gains control of possession for their team. outcome: always set to 1
50 Dispossessed Player is successfully tackled and loses possession of the ball. outcome: always set to 1
51 Error An error by a player, resulting in a shot or goal by the opposition. outcome: always set to 1
52 Keeper pick-up Goalkeeper only event; goalkeeper picks up the ball. outcome: always set to 1
53 Cross not claimed Goalkeeper only event; goalkeeper attempts to catch a cross and fails to make contact with the ball (does not claim the cross). outcome: always set to 1
54 Smother Goalkeeper only event; goalkeeper covers a ground ball in the box and collects it, winning possession. outcome: always set to 1
55 Offside provoked Awarded to the last defender when an offside decision is given against an attacking player. outcome: always set to 1
56 Shield ball opp A player uses their body to shield the ball from an opponent as it rolls out of play. outcome: always set to 1
57 Foul throw-in A player takes a throw-in incorrectly, resulting in the throw being awarded to the other team. These events come in pairs; one for the player who commits the foul throw, another for the team that is then awarded the throw-in.
outcome = 0 - Player who conceded the foul throw
outcome = 1 - Player who won the foul throw
58 Penalty faced Goalkeeper only event; goalkeeper faces an opposition penalty. outcome: always set to 0
59 Keeper Sweeper Goalkeeper only event; goalkeeper comes off their line to clear or claim the ball. outcome: always set to 0
60 Chance missed Used when a team/player does not actually have a shot on goal, but was in a good position to score and a player failed to generate a shot on goal - for example, only just missed receiving a pass. outcome: always set to 0
61 Ball touch A player unsuccessfully controls the ball and loses possession (for example, makes a bad touch on the ball).
outcome = 0: the player attempted to control the ball and failed (lost possession).
outcome = 1: the ball simply hit the player unintentionally, and they made no attempt to control it.
62 Event placeholder
63 Temp Save An event indicating a save has occurred but without full details. Event typeId 10 will follow shortly afterwards with full details. outcome: always set to 1
64 Resume The match has resumed on a new date after being abandoned mid-way through the game/during gameplay on a previous date
65 Contentious referee decision Any major talking point or error made by the referee - decision will be assigned to the relevant team.
66 Possession Data Note: No longer recorded in the feed
Possession event will appear every 5 mins
67 50/50 Two players run in and contend for a loose ball. These events come in pairs, one for each player, and indicates who gets to the ball first:
outcome = 0 player lost 50/50 duel
outcome = 1 player won 50/50 duel
Note: February 2025 - event is no longer collected.
68 Referee Drop Ball Occurs after an 'End Delay' event (typeId 28) when a match resumes, having been stopped by the referee with the ball in play. This event comes in pairs, with an event given to both teams on restart.
outcome = none (set to 1 by default)
69 Failed to Block Note - October 2019: No longer used (collected only for DFL between 2013/14 and 2016/17)
A player fails to block a pass or shot attempt, despite being a distance of one metre or less from the attempt (challenge lost). outcome: always set to 1
70 Injury Time Announcement Used when the amount of injury time is announced; the number of minutes added on is shown by an associated qualifier. outcome: always set to 1
71 Coach Setup The qualifiers on this event identify team coaches and their roles. outcome: always set to 1
72 Caught Offside Indicates that a player has been caught offside. outcome: always set to 1
73 Other Ball Contact Note: This is an automated extra event for DFL. It comes with a tackle or an interception and indicates if the player who made the tackle/interception retained the ball after this action or if the tackle/interception was a single ball touch (other ball contact with event type 'Interception' (8), type 'Defensive Clearance', or type 'Tackle Retained Ball'). outcome: always set to 1
74 Blocked Pass A player blocks a pass attempt by an opponent; similar to an Interception, but the player is already very close to the ball.
75 Delayed start The match start has been delayed.
76 Early end The match has had an early end.
77 Player Off Pitch Indicates that a player is now off the pitch.
78 Temp card
79 Coverage interruption Indicates that the game (and our analysis) was interrupted; outcome 0 = start of interruption, outcome 1 = end of interruption), qualifier 344 (video coverage lost). The event will be input by the analysts at the beginning and end of the interruption to explain why fewer events may be input during that time.
80 Drop of Ball A goalkeeper drops the ball close to himself with the intention to play it with their feet. Live (live data collection).
81 Obstacle Ball touches the goal frame, the referee, the corner flag or any other non-player object on the field (excludes attempts that hit the woodwork). Live (live data collection).
83 Attempted tackle A player has attempted to tackle an opponent but has been unsuccessful. Post (post-game data collection).
Note: This event will only be visible if the match is re-analysed within 24 hours of the match end time and date. Tier 14 and 15.
84 Deleted After Review This New Event type and type_id in order that the Contentious Referee Decision can be linked to it for all VAR cases. The deleted goal will now be a 'Deleted after review' event; we will now be able to link the CRD to this event, like we do to other non-deleted events. It keeps all the previous qualifier information, just like a regular deleted event does. (Added March 2021)

Useful Event Query Recipes

The following recipes map common football metrics to event typeId, outcome, extra-info, and qualifier-exclusion logic.

Query / Metric Type ID Outcome Extra Info Excluding Qualifiers
passes total 1 Include short corners where qualifier 6 is present but not qualifier 2 2, 107, 123
Passes successful 1 1 2, 107,123
passes unsuccessful 1 0 2, 107,123
Crosses Total (open play) 1 - 5,6
Successful Crosses Total(open) 1 1 5,6
Unsuccessful CrossesTotal (excl corners & Freekicks) 1 0 5,6
assists total 16 1 Value of 55 =event_id of theassisting pass
key passes total 13,14,15,60 - Value of 55 =event_id of the keypass
offensive passes total 1 - If (x < end_x) 2, 107,123,
offensive passes won 1 1 If (x < end_x) 2, 107,123,
offensive passes lost 1 0 If (x < end_x) 2, 107,123,
defensive/backwardpasses 1 - If (x > end_x) 2, 107,123,
sideway passes total 1 - If (x = end_x) 2, 107,123,
long passes total 1 - 2, 107,123,
long passes won 1 1 2, 107,123
long passes lost 1 0 2, 107,123
aerial total 44,4 with qualifier 264 -
aerial won 44,4 with qualifier 264 1
aerial lost 44,4 with qualifier 264 0
ground duels total 3,4 (ignore qualifier 264),7,45,54,50 -
ground duels won 3,4 (ignore qualifier 264),7,54 1
ground duels lost 3,4 (ignore qualifier 264),7,45,50 0 (except event type 50 which is always =1)
Free kicks takentotal 1,2, 13, 14, 15 or 16 -
Fouls total 4 -
Fouls won 4 1
Fouls conceded 4 0
handball conceded 4 0
corners total 1 - Crossed corners includequalifier 2, short corner withoutqualifier 2
corners into box- successful 1 1 If (83 < end_x < 100)If (21 < end_y < 78.9)
corners into box- unsuccessful 1 0 If (83 < end_x < 100)If (21 < end_y < 78.9)
interceptions 8 -
tackles won 7 1 or 0 Outcome 1 - tackle won andpossession won or ball wentout of play. Outcome 0 - onlytackle won no possession won
tackles lost - challenege 45 0
saves total 10 1
save (block by outfielder) 10 1
claim (goalkeeper catches cross) 11 1
clearance lost 12 0 as of October 2016, outcome="0" is no longer found on Clearance events
headed clearance won 12 1
headed clearance lost 12 0 as of October 2016, outcome="0" is no longer found on Clearance events
Total shots 13,14,15,16 - 28 (own goals)
shots on target 15,16 28 (own goals), 82 (blocked shots)
shots off target 13,14
Goals 16 1
Goals from open play 16 1
Goals from set plays 16 1
Goals from penalties 16 1
Own Goals 16 1 Team_id will be the team
headed shots ontarget 15,16 - 82 (blocked shots)
headed shots total 13,14,15,16,24 -
headed shots off target 13,14 -
shots blocked by outfielder 15 -
Total touches All events with these type IDs: 1, 2, 3, 4 (outcome = 1), 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 41, 42, 50, 54, 61, 73, 74 All
Successful take on (dribble) 3 1
Unsuccessful take on (dribble) 3 0 Qualifier 211 indicates an"overrun" which is notalways a duel event. Optional to include these.
Fouls won 4 1
Fouls conceded 4 0
Penalty conceded 4 0
Yellow card 17 -
2nd Yellow Cards 17 -
Red Cards 17 -