The MatchFormation endpoint returns the tactical formation detected during a match along with the average player positions on the pitch. The response includes:
  • Starting lineup formation
  • End-of-match formation
  • Average player locations
  • Player metadata (name, number, position)
  • Formation analysis for different match intervals
This endpoint is commonly used for:
  • Tactical analysis
  • Formation visualization
  • Broadcast graphics
  • Match reports and dashboards

​
Parameters

​
module
string
Module API fixed and cannot be changed. Always use api.
​
api
string
Endpoint name. Use MatchFormation.
​
version
string
API version. Use V2.
​
match_id
integer
Unique identifier of the match.
​
side
string
Team side for which the formation is requested. Possible values: home or away.
​
lang
string
Language of returned names. Supported values: en, ar.
​
response
string
Output format (json or xml).
​
key
string
API authentication key.

​
Example Request

curl "https://korastats.pro/pro/api.php?module=api&api=MatchFormation&version=V2&response=json&lang=en&match_id=25997&side=away"

{
  "result": "Success",
  "message": "Formation Detection",
  "data": {
    "_type": "FORMATION",
    "matchId": 25997,
    "matchName": "Zamalek 0x2 Al Ahly FC",
    "teamId": 2,
    "teamName": "Al Ahly FC",
    "lineupFormationName": "1-433",
    "endOfMatchFormationName": "1-522",
    "lineUpFormation": [
      {
        "_type": "PLAYER_AVERAGE_LOCATION",
        "player": {
          "intPlayerID": 370,
          "strNickNameEn": "Amr El Soulia",
          "intShirtNumber": 17,
          "strPositionEn": "CM"
        },
        "location": {
          "x": "52.8696",
          "y": "64.1957"
        }
      }
    ]
  }
}

​
Response Structure

​
Formation Information

FieldDescription
matchIdUnique match identifier
matchNameMatch name including teams and score
teamIdTeam identifier
teamNameTeam name
lineupFormationNameFormation used at kickoff
endOfMatchFormationNameFormation detected at the end of the match

​
Player Average Location

Each player object includes their average position on the pitch during the analyzed period.
FieldDescription
intPlayerIDUnique player ID
strNickNameEnPlayer display name
intShirtNumberShirt number
strPositionEnTactical position
location.xHorizontal coordinate on the pitch
location.yVertical coordinate on the pitch
Coordinates use the standard KoraStats pitch coordinate system:
  • X axis: 0 → 100 (goal to goal)
  • Y axis: 0 → 100 (left to right across the field)

​
Formation Intervals

The response may include formation analysis for different time segments of the match:
  • 1st Half
  • 2nd Half
  • 1st Half Q1
  • 1st Half Q2
  • 1st Half Q3
  • 2nd Half Q1
  • 2nd Half Q2
  • 2nd Half Q3
These intervals allow deeper analysis of tactical changes during the match.

​
Typical Use Cases

The formation data can be used to build:
  • Average position maps
  • Tactical shape visualizations
  • Heatmaps of player positioning
  • Broadcast tactical overlays
  • Post-match analysis reports
This endpoint is commonly used by coaches, analysts, scouts, and broadcasters.