Temporal & State Filters

Filter by game time periods, scene type, and possession state.

Match Timeline

Filter by game period (first half, second half, etc.).

Parameters

Parameter	Type	Required	Description
`type`	string	Yes	Must be `"match_timeline"`
`periods`	array	Yes	Periods to include

Available Periods

Period	Description
`first_half`	First half of the match
`second_half`	Second half of the match
`full_game`	Entire match (includes both halves)

Examples

First Half Only

{
  "filters": [
    {
      "type": "match_timeline",
      "periods": ["first_half"]
    }
  ]
}

Second Half Only

{
  "filters": [
    {
      "type": "match_timeline",
      "periods": ["second_half"]
    }
  ]
}

Both Halves (explicit)

{
  "filters": [
    {
      "type": "match_timeline",
      "periods": ["first_half", "second_half"]
    }
  ]
}

Notes

Period detection depends on video structure
Some videos may only have full_game if halves aren't clearly marked
Half-time break is typically excluded from both periods
Extra time periods are not currently supported

Scene

Filter by whether footage is analysable gameplay or not.

Parameters

Parameter	Type	Required	Default	Description
`type`	string	Yes	-	Must be `"scene"`
`is_analysable`	boolean	No	`true`	Filter analysable or non-analysable

Scene Types

Value	Description	Examples
`true`	Actual gameplay footage	Live play, set pieces
`false`	Non-gameplay footage	Replays, graphics, crowd shots, half-time

Examples

Only Analysable Scenes

{
  "filters": [
    {
      "type": "scene",
      "is_analysable": true
    }
  ]
}

Non-Analysable Scenes

{
  "filters": [
    {
      "type": "scene",
      "is_analysable": false
    }
  ]
}

Why Use This Filter?

Video broadcasts include replays, graphics, and other non-gameplay content. Without filtering, you might get results that include replays of events rather than the actual events.

Add scene filter to ensure results are from actual gameplay:

{
  "operator": "AND",
  "filters": [
    {
      "type": "scene",
      "is_analysable": true
    },
    {
      "type": "team_possession",
      "teams": ["team_0"]
    }
  ]
}

Always Include Scene Filter

For most analysis queries, include scene.is_analysable: true to ensure you're analyzing actual gameplay, not replays or graphics.

Exception: When you specifically want to find replay moments.

Team Possession

Filter by which team controls the ball.

Parameters

Parameter	Type	Required	Description
`type`	string	Yes	Must be `"team_possession"`
`teams`	array	Yes	Teams to include: `["team_0"]`, `["team_1"]`, or both

Team Identification

Value	Description
`team_0`	Team that started on the left side of the pitch
`team_1`	Team that started on the right side of the pitch

Finding Team Names

Use the Summary endpoint to get actual team names.

Examples

Single Team

{
  "filters": [
    {
      "type": "team_possession",
      "teams": ["team_0"]
    }
  ]
}

Either Team (known possession)

{
  "operator": "OR",
  "filters": [
    { "type": "team_possession", "teams": ["team_0"] },
    { "type": "team_possession", "teams": ["team_1"] }
  ]
}

Combined with Location

Find when Team 0 has the ball in their attacking half:

{
  "operator": "AND",
  "filters": [
    { "type": "team_possession", "teams": ["team_0"] },
    { "type": "ball_location", "x_min": 52.5, "x_max": 105 }
  ]
}

Understanding Results

The response shows intervals where the specified team had possession:

[
  { "start": 10.5, "end": 25.3, "label": "FC Example", "type": "team_possession" },
  { "start": 45.2, "end": 62.8, "label": "FC Example", "type": "team_possession" }
]

Gaps Between Intervals

Gaps may indicate:

Ball out of play
Unclear/contested possession
Transition moments
Non-analysable footage (replays)

Use Cases

Scenario	Configuration
Home team highlights	`teams: ["team_0"]`
Away team highlights	`teams: ["team_1"]`
All clear possession	Both teams with OR
Team attacks	Combine with ball_location in attacking third

Player Possession

Filter by which player has ball possession.

Parameters

Parameter	Type	Required	Description
`type`	string	Yes	Must be `"player_possession"`
`players`	array	Yes	List of player IDs

Player ID Format

{team}-{jersey}

team: 0 (left-starting) or 1 (right-starting)
jersey: Jersey number

Examples: "0-10", "1-7", "0-1"

Examples

Single Player

{
  "filters": [
    {
      "type": "player_possession",
      "players": ["0-10"]
    }
  ]
}

Multiple Players (any of them)

{
  "filters": [
    {
      "type": "player_possession",
      "players": ["0-10", "0-7", "0-9"]
    }
  ]
}

Striker Highlight Reel

{
  "filters": [
    {
      "type": "player_possession",
      "players": ["0-9", "0-11"]
    }
  ],
  "pad_sec": 5
}

Understanding Results

[
  { "start": 125.5, "end": 128.3, "label": "0-10", "type": "player_possession" },
  { "start": 340.2, "end": 342.8, "label": "0-10", "type": "player_possession" }
]

The label shows which player had possession during that interval.

Difference from Player Ball Proximity

Filter	What it detects
`player_possession`	Player identified as controlling the ball
`player_ball_proximity`	Player within physical distance of ball

Possession is more specific -- it means the player has actual control, not just proximity.

Use Cases

Scenario	Configuration
Player highlight reel	Single player, 5s padding
Attack trio analysis	Multiple forwards
Midfielder involvement	Midfield player IDs
Set piece taker	Player + ball location near goal

Combined Temporal & State Examples

Team attacks in second half

{
  "operator": "AND",
  "filters": [
    {
      "type": "match_timeline",
      "periods": ["second_half"]
    },
    {
      "type": "team_possession",
      "teams": ["team_0"]
    },
    {
      "type": "ball_location",
      "x_min": 70,
      "x_max": 105
    }
  ]
}

Player first half performance

{
  "operator": "AND",
  "filters": [
    {
      "type": "match_timeline",
      "periods": ["first_half"]
    },
    {
      "type": "player_possession",
      "players": ["0-10"]
    }
  ]
}

Clean possession data (live play only)

{
  "operator": "AND",
  "filters": [
    {
      "type": "scene",
      "is_analysable": true
    },
    {
      "type": "team_possession",
      "teams": ["team_0"]
    }
  ]
}

Penalty area action (live only)

{
  "operator": "AND",
  "filters": [
    {
      "type": "scene",
      "is_analysable": true
    },
    {
      "type": "ball_location",
      "x_min": 0,
      "x_max": 16.5,
      "y_min": 13.85,
      "y_max": 54.15
    }
  ]
}

Player possession during team attack

{
  "operator": "AND",
  "filters": [
    {
      "type": "player_possession",
      "players": ["0-10"]
    },
    {
      "type": "team_possession",
      "teams": ["team_0"]
    }
  ]
}

Second half player analysis

{
  "operator": "AND",
  "filters": [
    {
      "type": "match_timeline",
      "periods": ["second_half"]
    },
    {
      "type": "player_possession",
      "players": ["0-10"]
    }
  ]
}