Stats Perform logo

Sports Data API - Soccer - Match Possession Value Feed (MA30)

Overview

The Soccer Match Possession Value feed returns Possession Value metrics for all available players and teams in a queried soccer match.

The feed combines standard match metadata, competition metadata, team details, player lineup details, and Possession Value aggregates. Possession Value measures how actions affect the likelihood that the team in possession will score within the next 10 seconds.

Included Data Category Description
Match metadata Fixture ID, Opta legacy IDs, UTC and local date/time, coverage level, period configuration, attendance flags, VAR availability, and last update timestamp.
Competition metadata Competition, country, tournament calendar, stage, and series identifiers and names.
Contestants Home and away team identifiers, names, official names, short names, codes, and country data.
Venue Venue identifiers, neutrality flag, long name, and geolocation coordinates when available.
Team Possession Value Aggregate team Possession Value metrics, including positive and negative value by passes, crosses, take-ons, set plays, regains, and losing possession.
Player Possession Value Player-level Possession Value categories for lineup players when requested and available.
External reference https://www.theanalyst.com/eu/2021/03/what-is-possession-value/

Problem Statement & Use Cases

This API solves the business problem of quantifying how much value each team and player adds or loses through possession actions during a specific soccer match. Instead of evaluating contribution only through goals, assists, shots, or raw event counts, downstream systems can use Possession Value to measure whether actions increased or decreased the probability of a goal in the next 10 seconds.

Use Case Description
Player contribution analysis Rank players by total Possession Value and action-specific contribution categories such as passing, crossing, take-ons, regains, and set plays.
Team tactical evaluation Compare how each contestant creates or loses attacking value from possession phases during a match.
Live match analytics Power in-match widgets, dashboards, and editorial notes that explain which players or teams are generating value beyond the scoreline.
Model feature engineering Use team-level and player-level Possession Value metrics as structured features for predictive models, scouting workflows, and post-match reports.

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

Match State Polling Frequency
Queried match is live Once per minute.

Fixture and Locale Requirements

The /matchpossessionvalues feed must be queried for a specific fixture or match UUID and a valid locale value.

Requirement Detail
Fixture path parameter Use {fixtureUuid} in the request path to request Match Possession Value for a specific fixture.
Fixture query parameter Use fx to request Match Possession Value by an Opta legacy fixture ID.
Locale Use a valid locale value as defined by the Stats Perform global query parameters.
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.
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 and _clbk.
Placeholder braces Remove placeholder curly braces {} from production API calls. They are documentation examples only.
Case sensitivity Preserve exact URL, parameter, and operator case.
Base URL reference The base URL format is {protocol}://{requestDomain}/{feedResource}.

JSONP Requirements

If _fmt=jsonp is used, it must be combined with the callback parameter _clbk.

Constraint Requirement Reason
JSONP callback Use _fmt=jsonp together with _clbk. JSONP requires a callback wrapper function.
Fixed callback value Use a fixed _clbk value whenever possible. Random callback names can reduce cacheability and violate API best-practice logic.
JavaScript frameworks Override framework-generated random callback names, including defaults from common frameworks such as jQuery. Some frameworks generate random JSONP function names unless explicitly configured.

Lineup and Player-Level Availability

Player-level lineup Possession Value data is only returned when the request includes live=yes and lineups=yes, and when data is available.

Constraint Detail
Player lineup requirement The <player> element is only returned if live=yes and lineups=yes are included.
Scheduled or unavailable data If no data is available, such as for a scheduled fixture that is not playing and has not been played, the relevant live or lineup elements may be empty or absent.
Updates The feed is updated when new information becomes available. Use the polling guidance for live matches.

Endpoints

Base URL

https://api.statsperform.com

Feed Resource

/sdapi/v1/soccerdata/matchpossessionvalues

Get Match Possession Values by Fixture UUID Path Parameter

GET /sdapi/v1/soccerdata/matchpossessionvalues/{fixtureUuid}?{queryParameters}
Usage Feed
Get match possession values by fixture UUID using the path parameter method. /sdapi/v1/soccerdata/matchpossessionvalues/{fixtureUuid}?{queryParameters}

Get Match Possession Values by Fixture Legacy ID Query Parameter

GET /sdapi/v1/soccerdata/matchpossessionvalues?fx={fixtureLegacyId}&{queryParameters}
Usage Feed
Get match possession values by fixture using the fx query parameter. /sdapi/v1/soccerdata/matchpossessionvalues?fx={fixtureLegacyId}&{queryParameters}

Example Request Patterns

GET https://api.statsperform.com/sdapi/v1/soccerdata/matchpossessionvalues/{fixtureUuid}?_fmt={dataFormat}
GET https://api.statsperform.com/sdapi/v1/soccerdata/matchpossessionvalues?fx=urn:perform:opta:fixture:optamatchid&_fmt={dataFormat}

Query Parameters

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

Query the /matchpossessionvalues feed by a specific fixture UUID or by one supported Opta legacy fx ID.

Feed-Specific Query Parameters

Parameter Location Description Accepted Values / Format Example Request
{fixtureUuid} Path Get Match Possession Value data by the specified fixture UUID. Pass the fixture UUID directly in the request URL as the asset/resource ID. Fixture UUID GET https://api.statsperform.com/sdapi/v1/soccerdata/matchpossessionvalues/{fixtureUuid}?_fmt={dataFormat}
fx Query Get Match Possession Value data by the specified Opta legacy fixture ID. Opta legacy fixture ID, for example urn:perform:opta:fixture:optamatchid GET https://api.statsperform.com/sdapi/v1/soccerdata/matchpossessionvalues?fx=urn:perform:opta:fixture:optamatchid&_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.
_lcl Locale parameter. A valid locale value is required by the feed documentation; use values defined in the Global query parameters.
live Requests live data. Referenced by player-level availability rules. Use live=yes with lineups=yes to receive lineup player Possession Value data when available.
lineups Requests lineup data. Referenced by player-level availability rules. Use lineups=yes with live=yes to receive player lineup details when available.

Legacy ID Constraints

The fx parameter can filter by legacy IDs, but only one ID is supported.

Constraint Requirement
Single legacy ID only Do not pass multiple legacy IDs in a comma-separated list.
Legacy ID scope The documented fx legacy-ID method is for Opta legacy fixture IDs.
UUID path method Use {fixtureUuid} in the path for the canonical fixture UUID method.

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

PossessionValues>`

Property Value
Format XML only
Nesting matchPossessionValues
Description Required or optional root element of the fields related to match possession values.
JSON behavior Not present in JSON feed responses.
Attribute Required Description Values
None No This element has no documented attributes. N/A

`<match

Info>`

Property Value
Nesting matchPossessionValues/matchInfo
Description Required root element of the fields related to match information.
Attribute Required Description Values
id Yes Unique ID of the fixture or match. String; alphanumeric UUID
opId No Unique Opta match ID. Returned only if the feed is queried by Opta legacy ID. Empty string if the ID does not exist. String
ocId No Unique Opta match ID. Returned only if the feed is queried by Optacore legacy ID. Empty string if the ID does not exist. String
coverageLevel Yes Coverage level, also known as Tier, describing the data collection coverage level used by analysts and the data available through feeds. String; numeric
date Yes Fixture or match date in UTC. Date in format YYYY-MM-DDZ
time No Fixture or match start time in UTC. May be absent or empty until the time is confirmed; the feed is updated after confirmation. String in format hh:mm:ssZ
localDate Yes Fixture or match date in local time. Date in format YYYY-MM-DD
localTime No Fixture or match start time in local time. May be absent or empty until the time is confirmed; the feed is updated after confirmation. String in format hh:mm:ss
week No Week in which the match is taking place. String
postMatch No Indicates whether post-match collection is complete. If postMatch="1", post-match collection is complete. String
attendanceInfoId No Attendance information ID. Example values include 1 for Behind Closed Doors and 2 for Limited Audience. When returned, the attendance node and value normally under matchDetailsExtra are suppressed. String
attendanceInfo No Additional attendance information, such as Behind Closed Doors or Limited Audience. When returned, the attendance node and value normally under matchDetailsExtra are suppressed. String
numberOfPeriods No Number of periods to be played. A regular soccer match has two periods. Integer
periodLength No Duration of a period. A regular soccer match period is 45 minutes. Integer
overtimeLength No Length of overtime if the match goes beyond regular time. Integer
varEnabled No Indicates whether the fixture has VAR-related data. 0 means VAR info not collected, 1 means VAR info collected, and attribute absence means unknown. String; 0, 1, or attribute not present
lastUpdated Yes UTC timestamp when the fixture information or record was last updated. Date/Time in format YYYY-MM-DDThh:mm:ssZ

<description>

Property Value
Nesting matchPossessionValues/matchInfo/description
Description Optional description of the match or fixture, such as contestant names.
XML value String giving the description.
Attribute Required Description Values
None No This element has no documented attributes. N/A

<sport>

Property Value
Nesting matchPossessionValues/matchInfo/sport
Description Required root element of the related fields for the sport.
Attribute Required Description Values
id Yes Unique ID of the sport. String; alphanumeric UUID
name Yes Name of the sport. JSON only. String

<ruleset>

Property Value
Nesting matchPossessionValues/matchInfo/ruleset
Description Required root element of the related fields for the ruleset.
Attribute Required Description Values
id Yes Unique ID of the ruleset. String; alphanumeric
name Yes Name of the ruleset. JSON only. String

<competition>

Property Value
Nesting matchPossessionValues/matchInfo/competition
Description Required root element of the fields related to the competition.
Attribute Required Description Values
id Yes Unique ID of the competition. String; alphanumeric UUID
opId No Unique Opta competition ID. Returned only if the feed is queried by Opta legacy ID; otherwise not present. Empty string if no value exists. String
ocId No Unique Optacore competition ID. Returned only if the feed is queried by Optacore legacy ID; otherwise not present. Empty string if no value exists. String
name Yes Name of the competition. String
knownName No Known name of the competition. String
sponsorName Yes Sponsor name of the competition. String
competitionCode Yes Short three-digit competition code. String
competitionFormat Yes Format of the competition. String; one of Domestic league, Domestic cup, Domestic super cup, International cup, International super cup

<country> under <competition>

Property Value
Nesting matchPossessionValues/matchInfo/competition/country
Description Required root element of the fields related to the country that the competition is based in.
XML value String giving the country name.
Attribute Required Description Values
id Yes Unique ID of the country that the competition is based in. String; alphanumeric UUID
name No Name of the country. JSON only. String

`<tournament

Calendar>`

Property Value
Nesting matchPossessionValues/matchInfo/tournamentCalendar
Description Required root element of the fields related to a tournament calendar.
XML value String giving the tournament calendar name.
Attribute Required Description Values
id Yes Unique ID of the tournament calendar. String; alphanumeric UUID
opId No Unique Opta tournament calendar ID. Returned only if the feed is queried by Opta legacy ID; otherwise not present. Empty string if no value exists. String
ocId No Unique Opta tournament calendar ID. Returned only if the feed is queried by Optacore legacy ID; otherwise not present. Empty string if no value exists. String
startDate Yes Start date in UTC of the tournament calendar. Date in format YYYY-MM-DDZ
endDate Yes End date in UTC of the tournament calendar. Date in format YYYY-MM-DDZ
name No Name of the country that the tournament is based in. JSON only. String

<stage>

Property Value
Nesting matchPossessionValues/matchInfo/stage
Description Required root element of the fields related to the stage.
Attribute Required Description Values
id Yes Unique ID of the stage. String; alphanumeric UUID
opId No Unique Opta stage ID. Returned only if the feed is queried by Opta legacy ID; otherwise not present. Empty string if no value exists. String
ocId No Unique Opta stage ID. Returned only if the feed is queried by Optacore legacy ID; otherwise not present. Empty string if no value exists. String
formatId Yes Unique ID of the stage format. This identifies a specific type of stage; across seasons, a team can have the same format ID but a different stage ID because the stage ID is linked with stage and season. String; alphanumeric UUID
startDate Yes Start date in UTC of the stage. Date in format YYYY-MM-DDZ
endDate Yes End date in UTC of the stage. Date in format YYYY-MM-DDZ
name No Name of the stage that the competition is based in. JSON only. String

<series>

Property Value
Nesting matches/match/matchInfo/series
Description Optional root element of the fields related to the series. The element may not always be returned.
XML value String giving the series name.
Attribute Required Description Values
id Yes Unique ID of the series. String; alphanumeric UUID
ocId No 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 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 Order to display fixtures and standings for groups with the same vertical value. String
formatId Yes Unique ID related to the series format of the competition. String; alphanumeric UUID
name Yes Name of the series. JSON only. String

<contestants>

Property Value
Nesting matchPossessionValues/matchInfo/contestants
Description Optional root element of the fields related to contestants.
Attribute Required Description Values
None No This element has no documented attributes. N/A

<contestant> under `<match

Info>`

Property Value
Nesting matchPossessionValues/matchInfo/contestants/contestant
Description Optional root element of the fields related to a contestant. This element may not always be returned; for example, if a match is scheduled but contestants are not yet known, the record is updated once contestants are known.
Attribute Required Description Values
id Yes Unique ID of the contestant. String; alphanumeric UUID
opId No Unique Opta contestant ID. Returned only if the feed is queried by Opta legacy ID. Empty string if the ID does not exist. String
ocId No Unique Opta contestant ID. Returned only if the feed is queried by Optacore legacy ID. Empty string if the ID does not exist. String
name Yes Name of the contestant. String
shortName No Short name commonly used to refer to the contestant. String
officialName Yes Official name of the contestant. String
code No Three-character code used for the contestant name, often used on TV scoreboards. String
position Yes Indicates whether the contestant is the home or away side. String; one of home, away

<country> under <contestant>

Property Value
Nesting matchPossessionValues/matchInfo/contestants/contestant/country
Description Optional root element of the fields related to a contestant country. This element may not always be returned.
XML value String giving the country name.
Attribute Required Description Values
id Yes Unique ID of the country the contestant is from. String; alphanumeric UUID

<venue>

Property Value
Nesting matchPossessionValues/matchInfo/venue
Description Optional root element of the fields related to a venue. This element may not always be returned.
XML value String giving the venue name. In JSON and JSONP, the venue name is returned under shortName.
Attribute Required Description Values
id Yes Unique ID of the venue. String; alphanumeric UUID
neutral Yes Indicates whether the venue is neutral. The documented values are yes for neutral and no for not neutral. String; one of no, yes
opId No Unique Opta venue ID. Returned only if the feed is queried by Opta legacy ID; otherwise not present. Empty string if no value exists. String
ocId No Unique Opta venue ID. Returned only if the feed is queried by Optacore legacy ID; otherwise not present. Empty string if no value exists. String
longName Yes Long or extended venue name. String
latitude No Latitude coordinates for the venue location. String
longitude No Longitude coordinates for the venue location. String

`<possession

Value>`

Property Value
Nesting matchPossessionValues/possessionValue
Description Optional root element of the fields related to possession value.
Attribute Required Description Values
None No This element has no documented attributes. N/A

<contestant> under `<possession

Value>`

Property Value
Nesting matchPossessionValues/possessionValue/contestant
Description Optional root element of the fields related to a contestant in the possession-value section. This element may not always be returned; for example, if a match is scheduled but contestants are not yet known, the record is updated once contestants are known.
Attribute Required Description Values
id Yes Unique ID of the contestant. String; alphanumeric UUID
opId No Unique Opta contestant ID. Returned only if the feed is queried by Opta legacy ID. Empty string if the ID does not exist. String
ocId No Unique Opta contestant ID. Returned only if the feed is queried by Optacore legacy ID. Empty string if the ID does not exist. String

`<pv

Categories>` under possession-value contestant

Property Value
Nesting matchPossessionValues/possessionValue/contestant/pvCategories
Description Optional root element containing aggregate Possession Value categories for a contestant.
Attribute Required Description Values
totalPossessionValue No Aggregate Possession Value, measuring the likelihood of the team in possession scoring a goal in the next 10 seconds. String
totalPlusPV No Aggregation of all positive Possession Values. String
totalMinusPV No Aggregation of all negative Possession Values. String
totalPlusPass No Aggregation of all positive pass-related Possession Values. String
totalMinusPass No Aggregation of all negative pass-related Possession Values. String
totalPlusCross No Aggregation of all positive cross-related Possession Values. String
totalMinusCross No Aggregation of all negative cross-related Possession Values. String
totalPlusTakeOns No Aggregation of all positive take-on-related Possession Values. String
totalMinusTakeOn No Aggregation of all negative take-on-related Possession Values. String
totalPlusSetPlaysTaken No Aggregation of all positive set-play-taken Possession Values, including corners taken, free kicks taken, and throw-ins taken. String
totalMinusSetPlayTaken No Aggregation of all negative set-play-taken Possession Values, including corners taken, free kicks taken, and throw-ins taken. String
totalPlusSetPlaysDrawn No Aggregation of all positive set-play-drawn Possession Values. String
totalMinusSetPlayConceded No Aggregation of all negative set-play-conceded Possession Values. String
totalPlusRegains No Aggregation of all positive regains-related Possession Values. String
totalMinusLosingPossession No Aggregation of all negative losing-possession-related Possession Values. String

`<line

Up>`

Property Value
Nesting matchPossessionValues/possessionValue/contestant/lineUp
Description Optional root element of the fields related to the lineup.
Attribute Required Description Values
None No This element has no documented attributes. N/A

<player>

Property Value
Nesting matchPossessionValues/possessionValue/contestant/lineUp/player
Description Optional root element for each lineup player for a given team or contestant in a match.
Availability Only returned if the request includes live=yes and lineups=yes, and data is available.

If no data is available, such as for a scheduled fixture that is not playing and has not been played, the relevant live data or sub-elements may be empty or absent. The feed is updated when new information becomes available.

Attribute Required Description Values
playerId Yes Unique ID of the player. String; alphanumeric UUID
opPlayerId No Unique Opta ID of the player. Returned only if the feed is queried by Opta legacy ID; otherwise not present. Empty string if no value exists. String
ocPlayerId No Unique Opta ID of the player. Returned only if the feed is queried by Optacore legacy ID; otherwise not present. Empty string if no value exists. String
firstName Yes First name of the player. String
lastName Yes Last or second name of the player. String
birthName No Birth name of the person or player. String
matchName No Match name of the player. This node may not be returned for every player. If present, it may be preferable to use it instead of firstName and lastName; for example, Neymar may be returned as a known match name. String
shirtNumber Yes Shirt number of the player. Integer
position Yes Position of the player in the starting lineup. String; one of Goalkeeper, Wing Back, Defender, Defensive Midfielder, Attacking Midfielder, Midfielder, Striker, Substitute
positionSide No Area of the pitch where the player is positioned. Returned for all position values except Substitute. String; one of Left, Right, Centre, Left/Centre, Centre/Right
formationPlace Yes Individual position of the player within the formation, such as 1. For formation definitions, see the Match Events (MA3) guide, Appendix 5: Formations Explained. String

`<pv

Categories>under`

Property Value
Nesting matchPossessionValues/possessionValue/contestant/lineUp/player/pvCategories
Description Optional element containing player-level Possession Value category fields.
Attribute Required Description Values
timeMin No Minute of the match in which the Possession Value was updated. String
timeSec No Second attributed to the minute in the match in which the Possession Value was updated. String
periodId Yes Current match period. String; 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
totalPossessionValue No Aggregate Possession Value, measuring the likelihood of the team in possession scoring a goal in the next 10 seconds. String
totalPlusPV No Aggregation of all positive Possession Values. String
totalMinusPV No Aggregation of all negative Possession Values. String
totalPlusPass No Aggregation of all positive pass-related Possession Values. String
totalMinusPass No Aggregation of all negative pass-related Possession Values. String
totalPlusCross No Aggregation of all positive cross-related Possession Values. String
totalMinusCross No Aggregation of all negative cross-related Possession Values. String
totalPlusTakeOns No Aggregation of all positive take-on-related Possession Values. String
totalMinusTakeOn No Aggregation of all negative take-on-related Possession Values. String
totalPlusSetPlaysTaken No Aggregation of all positive set-play-taken Possession Values, including corners taken, free kicks taken, and throw-ins taken. String
totalMinusSetPlayTaken No Aggregation of all negative set-play-taken Possession Values, including corners taken, free kicks taken, and throw-ins taken. String
totalPlusSetPlaysDrawn No Aggregation of all positive set-play-drawn Possession Values. String
totalMinusSetPlayConceded No Aggregation of all negative set-play-conceded Possession Values. String
totalPlusRegains No Aggregation of all positive regains-related Possession Values. String
totalMinusLosingPossession No Aggregation of all negative losing-possession-related Possession Values. String