Filters Overview

Filters are used with the Query Intervals endpoint to find specific moments in a match. You compose a filter query by combining one or more filters with boolean logic.

Available Filters

Filter	Type Value	Description
Event Property	event_property	Query by event metadata (type, set piece, body part, length, etc.)
Frame State	frame_state	Query by player physical state (sprints, pressing distance)
Spatial	ball_location, player_ball_proximity	Ball position on pitch, player distance to ball
Temporal & State	match_timeline, scene, team_possession, player_possession	Game period, analysable footage, possession state
Ball Action	ball_action	Passes, drives, shots (legacy convenience filter)

Filter Structure

All filters have a type field plus type-specific parameters:

{
  "type": "filter_type_name",
  "param1": "value1",
  "param2": "value2"
}

Combining Filters

AND (default)

All conditions must be true at the same time:

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

OR

Any condition can be true:

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

Request Options

Beyond filters and operator, the request body supports these options:

Parameter	Type	Default	Description
operator	string	"AND"	How to combine filters: "AND" or "OR"
filters	array	-	List of filter objects
pad_sec	integer	5	Seconds of padding added before/after each interval
merge_results	bool	true	Merge overlapping intervals into one
include_pixel_coords	bool	false	Include player pixel coordinates in response (4 FPS)
existing_filters	array	[]	Pre-defined time windows (each with start, end, name)
gap_fill_sec	integer	5	Merge intervals within this gap (seconds)

Padding (pad_sec)

Adds time before and after each matched interval. Useful for creating clips with context:

{
  "filters": [
    { "type": "ball_action", "actions": ["shot"] }
  ],
  "pad_sec": 5
}

Merging (merge_results)

When true (default), overlapping intervals after padding are merged into a single interval. Set to false to keep each event as a separate interval:

{
  "merge_results": false,
  "filters": [
    { "type": "ball_action", "actions": ["pass"], "teams": ["team_0"] }
  ]
}

Pixel Coordinates (include_pixel_coords)

Returns normalized player positions in the video frame, sampled at 4 FPS. Useful for building UI overlays:

{
  "merge_results": false,
  "include_pixel_coords": true,
  "filters": [
    { "type": "ball_action", "actions": ["shot"], "players": ["0-10"] }
  ]
}

See Ball Action for full pixel coordinates documentation.

Common Patterns

Team attacking in final third

{
  "operator": "AND",
  "filters": [
    { "type": "team_possession", "teams": ["team_0"] },
    { "type": "ball_location", "x_min": 70, "x_max": 105 },
    { "type": "scene", "is_analysable": true }
  ]
}

Player highlight reel

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

Penalty area action

{
  "operator": "OR",
  "filters": [
    { "type": "ball_location", "x_min": 0, "x_max": 16.5, "y_min": 13.85, "y_max": 54.15 },
    { "type": "ball_location", "x_min": 88.5, "x_max": 105, "y_min": 13.85, "y_max": 54.15 }
  ]
}

Second half only

{
  "operator": "AND",
  "filters": [
    { "type": "match_timeline", "periods": ["second_half"] },
    { "type": "team_possession", "teams": ["team_1"] }
  ]
}

All shots by a player

{
  "filters": [
    { "type": "ball_action", "actions": ["shot"], "players": ["0-10"] }
  ]
}

Team passing sequences

{
  "filters": [
    { "type": "ball_action", "actions": ["pass"], "teams": ["team_0"] }
  ],
  "pad_sec": 3
}