Dealing with scores

Dealing with scores

All score-related data is stored within the score node. All of it’s attributes default to null. They change their values according to the match status.

The fullTime attribute

The score/fullTime attribute is key as it also acts as the running score. Its value is set to 0 immediately when the match status changes to IN_PLAY.

The halfTime attribute

As soon as the status changes to PAUSED, the score/halfTime attributes values change from it’s default null-value to the halftime score (that is: all goals shot during the first half). Note that it does not change any more from here on.

Regular finish

When the match status changes to FINISHED, the score/fullTime attribute indicates the final score.

Extra Time / Penalty Shootout

In case of knockout matches you have to pay attention to the score/duration attribute. It defaults to REGULAR but also accepts EXTRA_TIME and PENALTY_SHOOTOUT as value. It indicates when the match ended (e.g. match status FINISHED, score/duration EXTRA_TIME ⇒ 120 minutes, no penalties) - or, when the match is still running - it’s kind of an additional status of the match.

The optional score/extraTime, score/penalties nodes will appear and will be set to 0 as soon as duration is EXTRA_TIME and count up (only) the goals scored within extratime. PENALTY_SHOOTOUT works equivalent and score/penalties will only contain the goals within the penalty shootout.

So after a match you can either say "the match ended in penalty shootout" (taking the scores of the score/penalties) or "the match ended after a penalty shootout" (taking the fullTime score). At least in german we have that distinction and sport websites use it interchangeably. I personally prefer the latter.

Since v4 there is also the score/regularTime attribute which holds the goals scored after 90 minutes in case you want to display that as well.


Let’s take the quarter final of EC 1996 as a sample response. Germany won after penalty shootout:

  "score": {
      "winner": "HOME_TEAM",
      "duration": "PENALTY_SHOOTOUT",
      "fullTime": {
          "homeTeam": 7,
          "awayTeam": 6
      "halfTime": {
          "homeTeam": 1,
          "awayTeam": 1
      "regularTime": {
          "homeTeam": 1,
          "awayTeam": 1
      "extraTime": {
          "homeTeam": 0,
          "awayTeam": 0
      "penalties": {
          "homeTeam": 6,
          "awayTeam": 5