​
Overview

The Match Possession Distribution API returns a live spatial breakdown of each team’s possession across three pitch zones: the defensive third (DEF), middle third (MID), and attacking third (FWD). For both the home and away teams, the response provides:
  • Total: the total number of possession observations included in the distribution.
  • Abs: the absolute number of observations recorded in a specific pitch zone.
  • Percent: that zone’s share of the team’s own total, returned as a ratio between 0 and 1.
This endpoint describes where each team has its possession. The zone percentages are calculated independently for each team and do not represent the overall home-versus-away possession share. For example, a home DEF.Percent value of 0.59 means that 59% of the home team’s counted possession occurred in its defensive third. The values represent the latest data available when the request is made and may change as live match events are processed.

​
Typical Use Cases

  • Build live possession-distribution graphics.
  • Compare where each team is controlling the ball.
  • Show defensive-, middle-, and attacking-third possession shares.
  • Feed broadcast graphics and match-center visualizations.
  • Identify whether a team is circulating deeply or sustaining possession higher up the pitch.
  • Create post-match spatial possession comparisons.

​
Parameters

​
module
string
required
The API module. This value is fixed and must always be api.
​
api
string
required
The endpoint name. This value is fixed and must always be MatchPossessionDistribution.
​
version
string
required
The API version. Use V2.
​
match_id
integer
required
The unique KoraStats match identifier. In this example, 78199 identifies South Africa vs Senegal.
​
lang
string
required
The response language code. Use en for English.
​
response
string
required
The response format. Use json.
​
key
string
required
Your KoraStats API key. Keep this value secure and do not expose it in public or client-side applications.

​
Endpoint

GET https://premium.korastats.pro/api.php 
https://premium.korastats.pro/api.php?module=api&api=MatchPossessionDistribution&version=V2&match_id=78199&lang=en&response=json&key=YOUR_API_KEY

​
Code Examples

curl --get "https://premium.korastats.pro/api.php" \
  --data-urlencode "module=api" \
  --data-urlencode "api=MatchPossessionDistribution" \
  --data-urlencode "version=V2" \
  --data-urlencode "match_id=78199" \
  --data-urlencode "lang=en" \
  --data-urlencode "response=json" \
  --data-urlencode "key=YOUR_API_KEY"

​
Response Example

{
  "result": true,
  "title": "Success",
  "message": "Live match possession retrieved",
  "object": {
    "_type": "POSSESSION_DISTRIBUTION",
    "match": {
      "id": 78199,
      "name": "South Africa x Senegal"
    },
    "home": {
      "_type": "TEAM",
      "id": 2140,
      "name": "South Africa"
    },
    "away": {
      "_type": "TEAM",
      "id": 23247,
      "name": "Senegal"
    },
    "possession": {
      "home": {
        "Total": 1115,
        "DEF": {
          "Abs": 657,
          "Percent": 0.59
        },
        "MID": {
          "Abs": 282,
          "Percent": 0.25
        },
        "FWD": {
          "Abs": 176,
          "Percent": 0.16000000000000003
        }
      },
      "away": {
        "Total": 803,
        "DEF": {
          "Abs": 496,
          "Percent": 0.62
        },
        "MID": {
          "Abs": 206,
          "Percent": 0.26
        },
        "FWD": {
          "Abs": 101,
          "Percent": 0.12
        }
      }
    }
  }
}

​
Response Fields

​
Response Envelope

FieldTypeDescription
resultbooleanIndicates whether the request completed successfully.
titlestringShort response status title.
messagestringHuman-readable result message.
objectobjectMatch, team, and possession-distribution data.

​
Possession Distribution Object

FieldTypeDescription
object._typestringObject discriminator. The value is POSSESSION_DISTRIBUTION.
object.matchobjectMatch summary.
object.homeobjectHome-team summary.
object.awayobjectAway-team summary.
object.possessionobjectPossession distribution for the home and away teams.
object.possession.homeobjectHome team’s zone distribution.
object.possession.awayobjectAway team’s zone distribution.

​
Match Object

FieldTypeDescription
object.match.idintegerUnique match identifier.
object.match.namestringMatch display name.

​
Team Objects

The home and away objects use the same schema.
FieldTypeDescription
`object.[homeaway]._type`stringObject discriminator. The value is TEAM.
`object.[homeaway].id`integerUnique team identifier.
`object.[homeaway].name`stringTeam name.

​
Team Possession Fields

The same structure appears under object.possession.home and object.possession.away. In the paths below, [side] represents home or away, and [zone] represents DEF, MID, or FWD.
FieldTypeDescription
object.possession.[side].TotalintegerTotal possession observations used for the team’s zone distribution. Equal to the sum of the three zone Abs values.
object.possession.[side].[zone]objectPossession values for one pitch zone.
object.possession.[side].[zone].AbsintegerAbsolute number of possession observations recorded in the zone.
object.possession.[side].[zone].PercentnumberZone’s share of the team’s Total, returned as a ratio from 0 to 1.

​
Zone Definitions

ZonePitch AreaDescription
DEFDefensive thirdPossession recorded in the team’s defensive third.
MIDMiddle thirdPossession recorded in the middle third of the pitch.
FWDAttacking thirdPossession recorded in the team’s attacking or final third.
The three zone percentages belong to one team and should total approximately 1.0, subject to rounding. They do not compare the home team’s overall possession against the away team’s overall possession.
For display, multiply Percent by 100. For example, 0.59 becomes 59%, 0.25 becomes 25%, and 0.16 becomes 16%.
JSON floating-point values can contain extra precision, such as 0.16000000000000003. Round the value for display—for example, to two decimal places as a ratio or to a whole-number percentage. When validating totals, use a small numeric tolerance instead of requiring exact floating-point equality.

​
Error Response

If match_id is missing, the API returns a bad-request response using the standard KoraStats error envelope. 
{
  "result": false,
  "title": "Bad Request",
  "message": "Match id not sent."
}