Match Momentum

Returns the momentum flow of a match as chart-ready timeline points. Positive values represent the home team and negative values represent the away team. The endpoint supports both a full response and incremental live updates. Momentum is always recalculated using the complete match history; after_second only filters the items returned in the response.

Timeline points are generated at 60-second intervals and use a normalized range from -1 to 1.

Request

Full response

curl --request GET \
  --url 'https://premium.korastats.pro/api.php?module=api&api=MatchMomentum&version=V2&response=json&lang=en&match_id=128333&key=YOUR_API_KEY'

Incremental live update

curl --request GET \
  --url 'https://premium.korastats.pro/api.php?module=api&api=MatchMomentum&version=V2&response=json&lang=en&match_id=128333&after_second=4800&key=YOUR_API_KEY'

Query parameters

module

string

required

Must be api.

api

string

required

Must be MatchMomentum.

version

string

required

API version. Use V2.

key

string

required

Your KoraStats API key.

match_id

integer

required

Unique KoraStats match ID. Must be a positive integer.

after_second

integer

Returns timeline points and goals strictly after this match second. Completed phases ending at or before this second are excluded, while a phase that continues beyond it is included.Must be zero or a positive integer. Omit this parameter to retrieve the complete timeline.

include

string

default:"phases,goals"

Comma-separated optional response sections. Accepted values are phases, goals, and inputs.If omitted, phases and goals are included. Passing include=inputs returns only the standard momentum response plus calculation inputs. Use include=phases,goals,inputs to return all optional sections.

lang

string

default:"en"

Response language code.

response

string

default:"json"

Response format. Use json.

Understanding momentum

Value	Meaning
Greater than `0`	Momentum favors the home team
Less than `0`	Momentum favors the away team
Near `0`	The match is balanced
`1`	Maximum home-team momentum
`-1`	Maximum away-team momentum

strDominantTeam and strPhase are separate classifications. A point can therefore have strDominantTeam: "BALANCED" while its phase remains HOME_CONTROL or AWAY_CONTROL.

Phase values

`strPhase` / `strType`	Description
`HOME_STRONG_CONTROL`	Strong home-team control
`HOME_CONTROL`	Home-team control
`BALANCED`	No team is in a control phase
`AWAY_CONTROL`	Away-team control
`AWAY_STRONG_CONTROL`	Strong away-team control

Full response example

{
  "result": true,
  "title": "Success",
  "message": "Match Clube de Regatas Brasil 4x2 Ponte Preta momentum calculated",
  "object": {
    "objMatch": {
      "intID": 128333,
      "strName": "Clube de Regatas Brasil 4x2 Ponte Preta",
      "strResponseType": "FULL",
      "intAfterSecond": null,
      "dtGeneratedAt": "2026-07-19T15:23:51Z"
    },
    "objTeams": {
      "objHome": {
        "intID": 23890,
        "strName": "Clube de Regatas Brasil"
      },
      "objAway": {
        "intID": 23909,
        "strName": "Ponte Preta"
      }
    },
    "objMomentum": {
      "intIntervalSeconds": 60,
      "objRange": {
        "decMinimum": -1,
        "decMaximum": 1
      },
      "objDirection": {
        "strPositive": "HOME",
        "strNegative": "AWAY"
      },
      "intPointCount": 98,
      "arrPoints": [
        {
          "intSecond": 0,
          "strTime": "00:00",
          "decValue": 0.301,
          "strDominantTeam": "HOME",
          "strPhase": "HOME_CONTROL"
        },
        {
          "intSecond": 60,
          "strTime": "01:00",
          "decValue": 0.296,
          "strDominantTeam": "HOME",
          "strPhase": "HOME_CONTROL"
        }
      ]
    },
    "arrPhases": [
      {
        "strType": "HOME_CONTROL",
        "strTeamSide": "HOME",
        "strStrength": "NORMAL",
        "intStartSecond": 0,
        "intEndSecond": 300,
        "strStartTime": "00:00",
        "strEndTime": "05:00"
      }
    ],
    "arrGoals": [
      {
        "intEventID": 224755219,
        "intSecond": 1650,
        "strTime": "27:30",
        "intTeamID": 23909,
        "strTeamSide": "AWAY",
        "objPlayer": {
          "intID": 189383,
          "strName": "David da Hora",
          "intShirtNumber": 70
        },
        "objScore": {
          "intHome": 0,
          "intAway": 1
        }
      }
    ]
  }
}

Response fields

Envelope

result

boolean

Indicates whether the request succeeded.

title

string

Short response status.

message

string

Human-readable response message.

object

Match momentum payload.

Match and teams

object.objMatch

object

Match and response metadata.

Show properties

intID

integer

Unique match ID.

strName

string

Display name of the match.

strResponseType

string

FULL when after_second is omitted; otherwise INCREMENTAL.

intAfterSecond

integer | null

The requested incremental cursor, or null for a full response.

dtGeneratedAt

string

UTC generation time in ISO 8601 format.

object.objTeams

object

Home and away team identities. Each team contains intID and strName.

Momentum

object.objMomentum.intIntervalSeconds

integer

Timeline interval in seconds. Currently 60.

object.objMomentum.objRange

object

Minimum and maximum possible momentum values.

object.objMomentum.objDirection

object

Defines which team is represented by positive and negative values.

object.objMomentum.intPointCount

integer

Number of points returned in arrPoints, after incremental filtering when applicable.

object.objMomentum.arrPoints

object[]

Ordered, chart-ready momentum points.

Show point properties

intSecond

integer

Elapsed match time in seconds.

strTime

string

Display time in MM:SS format. Minutes can exceed 59.

decValue

number

Momentum value rounded to three decimal places.

strDominantTeam

string

One of HOME, AWAY, or BALANCED.

strPhase

string

Control phase assigned to this point.

objInputs

object

Present only when include contains inputs.

Phases

object.arrPhases

object[]

Continuous control phases. Returned by default and omitted when include does not contain phases.strTeamSide and strStrength are null for a balanced phase. Otherwise, strStrength is NORMAL or STRONG.

Goals

object.arrGoals

object[]

Goal annotations for the timeline. Returned by default and omitted when include does not contain goals.Each goal includes its match-event ID, time, team, scorer, shirt number when available, and the score immediately after the goal.

Calculation inputs

When include=inputs is requested, each timeline point also contains:

{
  "objInputs": {
    "objHome": {
      "decScore": 20.55,
      "arrStats": {
        "intPossession": 61,
        "intBallRecoveries": 7,
        "intFinalThirdEntries": 6,
        "intFinalThirdActions": 34,
        "intShots": 1,
        "intCrosses": 3,
        "intFoulsWon": 2,
        "intDangerousActions": 47
      }
    },
    "objAway": {
      "decScore": 11.4,
      "arrStats": {
        "intPossession": 45,
        "intBallRecoveries": 4,
        "intFinalThirdEntries": 2,
        "intFinalThirdActions": 9,
        "intShots": 0,
        "intCrosses": 0,
        "intFoulsWon": 1,
        "intDangerousActions": 11
      }
    },
    "decMomentumRaw": 0.286
  }
}

Input statistics are calculation diagnostics and increase the response size. For most media and visualization integrations, use the default response.

Live integration

Request the endpoint without after_second to initialize the complete chart.
Store the greatest intSecond received in arrPoints.
On the next poll, send that value as after_second.
Append the returned points and goals by their unique time or ID.
Replace overlapping/current phase data rather than blindly appending phases, because an active phase may have started before the requested cursor.

For example, after_second=4800 returns points beginning at 4860; the point at 4800 is not repeated.

An incremental response is not calculated from only the newly received match events. The server uses the full match history to preserve consistency, then filters the response exclusively after the requested second.

Incremental response example

{
  "result": true,
  "title": "Success",
  "message": "Match Clube de Regatas Brasil 4x2 Ponte Preta momentum updated",
  "object": {
    "objMatch": {
      "intID": 128333,
      "strName": "Clube de Regatas Brasil 4x2 Ponte Preta",
      "strResponseType": "INCREMENTAL",
      "intAfterSecond": 4800,
      "dtGeneratedAt": "2026-07-19T15:24:00Z"
    },
    "objTeams": {
      "objHome": {
        "intID": 23890,
        "strName": "Clube de Regatas Brasil"
      },
      "objAway": {
        "intID": 23909,
        "strName": "Ponte Preta"
      }
    },
    "objMomentum": {
      "intIntervalSeconds": 60,
      "objRange": {
        "decMinimum": -1,
        "decMaximum": 1
      },
      "objDirection": {
        "strPositive": "HOME",
        "strNegative": "AWAY"
      },
      "intPointCount": 17,
      "arrPoints": [
        {
          "intSecond": 4860,
          "strTime": "81:00",
          "decValue": -0.57,
          "strDominantTeam": "AWAY",
          "strPhase": "AWAY_STRONG_CONTROL"
        }
      ]
    },
    "arrPhases": [
      {
        "strType": "AWAY_STRONG_CONTROL",
        "strTeamSide": "AWAY",
        "strStrength": "STRONG",
        "intStartSecond": 4740,
        "intEndSecond": 5280,
        "strStartTime": "79:00",
        "strEndTime": "88:00"
      }
    ],
    "arrGoals": [
      {
        "intEventID": 224783691,
        "intSecond": 5622,
        "strTime": "93:42",
        "intTeamID": 23890,
        "strTeamSide": "HOME",
        "objPlayer": {
          "intID": 228092,
          "strName": "Luiz Phellype",
          "intShirtNumber": 27
        },
        "objScore": {
          "intHome": 4,
          "intAway": 2
        }
      }
    ]
  }
}

Errors

HTTP status	Condition
`400 Bad Request`	`match_id` is missing, non-numeric, or not positive
`400 Bad Request`	`after_second` is negative or non-numeric
`404 Not Found`	The requested match does not exist

400 - Invalid match ID

{
  "result": false,
  "title": "Bad Request",
  "message": "A valid match_id is required."
}

400 - Invalid incremental cursor

{
  "result": false,
  "title": "Bad Request",
  "message": "after_second must be zero or a positive integer."
}

404 - Match not found

{
  "result": false,
  "title": "Not Found",
  "message": "Match not found."
}

API documentation

Tournament Endpoints

Season Endpoints

Match Endpoints

Player Endpoints

Team Endpoints

Coach Endpoints

Referee Endpoints

Videos Endpoints

3rd Party Integration

Misc Endpoint

Request

Query parameters

Understanding momentum

Phase values

Full response example

Response fields

Envelope

Match and teams

Momentum

Phases

Goals

Calculation inputs

Live integration

Incremental response example

Errors

API documentation

Tournament Endpoints

Season Endpoints

Match Endpoints

Player Endpoints

Team Endpoints

Coach Endpoints

Referee Endpoints

Videos Endpoints

3rd Party Integration

Misc Endpoint

​Request

​Query parameters

​Understanding momentum

​Phase values

​Full response example

​Response fields

​Envelope

​Match and teams

​Momentum

​Phases

​Goals

​Calculation inputs

​Live integration

​Incremental response example

​Errors

Request

Query parameters

Understanding momentum

Phase values

Full response example

Response fields

Envelope

Match and teams

Momentum

Phases

Goals

Calculation inputs

Live integration

Incremental response example

Errors