TrackedEvent

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/datasportsapi/json-schema/datasportsapi-tracked-event-schema.json",
  "title": "TrackedEvent",
  "description": "One entry of the tracked play-by-play, with where it happened (football, tennis, basketball). Tennis and football are delivered live — football roughly 9 seconds after the moment (about 15 at most) for goals, shots, cards, substitutions, set pieces and the flow of play, while passes and most of the detail follow in the post-match read. Basketball events mostly come later, with the post-match read of the data.",
  "x-generated": "2026-11-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/datasportsapi-openapi.json#/components/schemas/TrackedEvent",
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "description": "Key that identifies the event within the fixture and never changes; REST and WebSocket use the same key."
    },
    "type": {
      "type": "string",
      "description": "What happened, in camelCase. Football: goal, attemptAtGoal, pass, cross, dribble, corner, freeKick, throwIn, goalKick, penalty, foul, offside, duel, tackle, interception, clearance, block, save, yellowCard, secondYellowCard, redCard, substitution; flowAttack / flowDangerousAttack / flowBallSafe describe the flow of play (side is the team in possession, position is where the ball is — together, the live state of the match); possibleCorner / possibleGoal / possiblePenalty (and the matching …Cancelled types) mark a decision still pending; possessionChange has no side; also kickOff, periodStatus, injuryTime, injury, backFromInjury, interruptionStart / interruptionOver, videoReview and more. Tennis: serve, fault, let, point, challenge, ballSituation (where the ball is), playerSituation (where a player is) and more. Basketball: freeThrow, twoPointer, threePointer, rebound, steal, block, turnover, foul, possessionChange, substitutionIn / substitutionOut, timeoutStart, periodStatus and more. Further types may appear; ignore any you do not recognise, or show it as information only."
    },
    "at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "description": "Moment of the event."
    },
    "side": {
      "anyOf": [
        {
          "$ref": "#/$defs/Side"
        },
        {
          "type": "null"
        }
      ],
      "description": "Side credited with the event; null for neutral ones such as a period change or a loose ball."
    },
    "minute": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Football: match minute. Null for other sports. Unit: minutes."
    },
    "second": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Football: match clock in seconds. Null for other sports. Unit: seconds."
    },
    "period": {
      "anyOf": [
        {
          "$ref": "#/$defs/PeriodKey"
        },
        {
          "type": "null"
        }
      ],
      "description": "Basketball: period in which it happened (period1…period4, overtime). Null for other sports."
    },
    "set": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Tennis: set number."
    },
    "game": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Tennis: game number in the set."
    },
    "position": {
      "anyOf": [
        {
          "$ref": "#/$defs/TrackingSpot"
        },
        {
          "type": "null"
        }
      ],
      "description": "Location of the event: for football (pass origin, shot, foul, …) and basketball (shot, foul, rebound, …) on the 0–100 frame; for tennis ballSituation / playerSituation in millimetres, with z as the ball’s height. Null when the source gives no spot."
    },
    "endPosition": {
      "anyOf": [
        {
          "$ref": "#/$defs/TrackingSpot"
        },
        {
          "type": "null"
        }
      ],
      "description": "Football passes: the spot the ball was played to."
    },
    "player": {
      "anyOf": [
        {
          "$ref": "#/$defs/TrackedPlayer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Who performed it, if the source names someone the squad list contains."
    },
    "assist": {
      "anyOf": [
        {
          "$ref": "#/$defs/TrackedPlayer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Football goals: who provided the assist."
    },
    "playerIn": {
      "anyOf": [
        {
          "$ref": "#/$defs/TrackedPlayer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Football substitutions: who came on."
    },
    "playerOut": {
      "anyOf": [
        {
          "$ref": "#/$defs/TrackedPlayer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Football substitutions: who went off."
    },
    "outcome": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Result, in camelCase: complete / incomplete for passes; onTarget, offTarget, blocked, woodwork, deflectedOffTarget and more for shots; made / missed in basketball."
    },
    "goalType": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Football goals: how it was scored, in camelCase (shot, header, ownGoal, penalty, …)."
    },
    "serving": {
      "anyOf": [
        {
          "$ref": "#/$defs/Side"
        },
        {
          "type": "null"
        }
      ],
      "description": "Tennis points: who was serving."
    },
    "gameScore": {
      "anyOf": [
        {
          "$ref": "#/$defs/TennisGameScore"
        },
        {
          "type": "null"
        }
      ],
      "description": "Tennis points: the score in the game once the point was played."
    },
    "pointOutcome": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Tennis points: how the point was won, in camelCase (standard, ace, doubleFault, …)."
    },
    "shots": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Tennis points: number of shots in the rally, when provided."
    }
  },
  "required": [
    "key",
    "type",
    "at",
    "side",
    "minute",
    "second",
    "period",
    "set",
    "game",
    "position",
    "endPosition",
    "player",
    "assist",
    "playerIn",
    "playerOut",
    "outcome",
    "goalType",
    "serving",
    "gameScore",
    "pointOutcome",
    "shots"
  ],
  "$defs": {
    "PeriodKey": {
      "type": "string",
      "pattern": "^(?:period[1-9][0-9]*|inning[1-9][0-9]*|extra[12]|overtime|penalties)$",
      "description": "periodN: Regulation period number N. What a period is depends on the sport: a half in football, rugby, handball, futsal, minifootball and bandy; a quarter in basketball, American football and water polo; a period in ice hockey and floorball; a set in tennis, volleyball, table tennis, badminton and padel; an inning in baseball; a round in combat sports; a map / game in esports; a leg / frame block in darts and snooker. inningN: Cricket only: innings number N. extra1: Football and futsal: the opening half of extra time. extra2: Football and futsal: the closing half of extra time. overtime: Every overtime period summed into one value (American football, basketball, handball, ice hockey, water polo, …). In baseball it holds the runs scored in extra innings, and only when the source provides no inning-by-inning split (period10, …). penalties: The penalty shoot-out, which appears only as a `status.period` value; its score is kept in ScoreSide.penalties, not under a `periods` key."
    },
    "Side": {
      "type": "string",
      "enum": [
        "home",
        "away"
      ],
      "description": "One of the two sides in a fixture.",
      "x-enumDescriptions": {
        "home": "The side listed as home in the fixture.",
        "away": "The side listed as away in the fixture."
      }
    },
    "TennisGameScore": {
      "type": "object",
      "description": "The score within a tennis game after a point.",
      "properties": {
        "home": {
          "type": "string",
          "description": "Home side’s points in the current game — 0, 15, 30, 40 or A (advantage) — or the tie-break count."
        },
        "away": {
          "type": "string",
          "description": "Points of the away side in the game."
        }
      },
      "required": [
        "home",
        "away"
      ]
    },
    "TrackedPlayer": {
      "type": "object",
      "description": "A player that a tracked event names, taken from the match squad. There is no id: tracked players are not linked to DataSportsAPI player ids.",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name as displayed, given name first."
        },
        "shirtNumber": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "description": "Number on his shirt in this match."
        },
        "side": {
          "anyOf": [
            {
              "$ref": "#/$defs/Side"
            },
            {
              "type": "null"
            }
          ],
          "description": "Which side the player is on."
        }
      },
      "required": [
        "name",
        "shirtNumber",
        "side"
      ]
    },
    "TrackingSpot": {
      "type": "object",
      "description": "A spot expressed in the coordinate frame of the fixture (see TrackingSummary.coordinates).",
      "properties": {
        "x": {
          "type": "number",
          "description": "Position along the pitch, court or rink, in the fixture’s frame (TrackingCoordinates)."
        },
        "y": {
          "type": "number",
          "description": "Position across the pitch, court or rink, in that same frame."
        },
        "z": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Height of the tennis ball above the court in millimetres (tennis ball positions only); null elsewhere."
        }
      },
      "required": [
        "x",
        "y",
        "z"
      ]
    }
  }
}