Spatial Filters

Filter by physical positions on the pitch: ball location and player proximity to the ball.

---

Ball Location

Filter by ball position on the pitch.

Parameters

Parameter	Type	Default	Range	Description
type	string	-	-	Must be "ball_location"
x_min	float	0	-5 to 110	Minimum X coordinate (meters)
x_max	float	105	-5 to 110	Maximum X coordinate (meters)
y_min	float	0	-5 to 75	Minimum Y coordinate (meters)
y_max	float	68	-5 to 75	Maximum Y coordinate (meters)
team_side_perspective	string	null	team_0, team_1	Flip coordinates for team's attacking half

Pitch Coordinates

The coordinate system has its origin at the bottom-left corner, with Y increasing upward:

        0m                    52.5m                   105m
    ┌─────────────────────────┬─────────────────────────┐ 68m
    │                         │                         │
    │   ┌───┐                 │                 ┌───┐   │
    │   │   │    Team 0       │      Team 1     │   │   │
    │   │   │    Defensive    │     Defensive   │   │   │
    │   │   │      Half       │       Half      │   │   │
    │   └───┘                 │                 └───┘   │
    │                         │                         │
    └─────────────────────────┴─────────────────────────┘ 0m
         Left                                    Right

See Pitch Coordinates for full details.

Examples

Left Third (0-35m)

{
  "filters": [
    {
      "type": "ball_location",
      "x_min": 0,
      "x_max": 35
    }
  ]
}

Left Penalty Area

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

Both Penalty Areas (OR)

{
  "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
    }
  ]
}

Wing Play (left wing)

{
  "filters": [
    {
      "type": "ball_location",
      "x_min": 0,
      "x_max": 105,
      "y_min": 0,
      "y_max": 15
    }
  ]
}

Team Perspective

Use team_side_perspective to define zones relative to a team's attacking direction:

{
  "filters": [
    {
      "type": "ball_location",
      "x_min": 70,
      "x_max": 105,
      "team_side_perspective": "team_0"
    }
  ]
}

This finds ball in Team 0's attacking third, automatically adjusting coordinates if the team switched sides.

Common Zones

Zone	x_min	x_max	y_min	y_max
Left third	0	35	0	68
Middle third	35	70	0	68
Right third	70	105	0	68
Left penalty area	0	16.5	13.85	54.15
Right penalty area	88.5	105	13.85	54.15
Left 6-yard box	0	5.5	24.85	43.15
Right 6-yard box	99.5	105	24.85	43.15
Center circle	42.5	62.5	24.15	43.85
Left wing	0	105	0	15
Right wing	0	105	53	68

---

Player Ball Proximity

Filter by player distance to the ball.

Parameters

Parameter	Type	Required	Range	Description
type	string	Yes	-	Must be "player_ball_proximity"
players	array	Yes	-	List of player IDs
threshold	float	No	0.1-100	Distance in meters (default: 5)

Player ID Format

{team}-{jersey}

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

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

Finding Player IDs

Use Summary endpoint to get available player IDs.

Examples

Single Player Near Ball

{
  "filters": [
    {
      "type": "player_ball_proximity",
      "players": ["0-10"],
      "threshold": 5
    }
  ]
}

Tight Ball Control (3m)

{
  "filters": [
    {
      "type": "player_ball_proximity",
      "players": ["0-10"],
      "threshold": 3
    }
  ]
}

Multiple Players

Find moments when ANY of these players is near the ball:

{
  "filters": [
    {
      "type": "player_ball_proximity",
      "players": ["0-10", "0-7", "0-11"],
      "threshold": 5
    }
  ]
}

Goalkeeper Involvement

{
  "filters": [
    {
      "type": "player_ball_proximity",
      "players": ["0-1"],
      "threshold": 3
    }
  ]
}

Understanding Threshold

Threshold	Interpretation
1-2m	Direct ball control, dribbling
3-5m	Active involvement, receiving pass
5-10m	Nearby, potential involvement
10-15m	Defensive pressure zone

Difference from Player Possession

Filter	Detects
player_ball_proximity	Player within distance of ball
player_possession	Player identified as having control

Use proximity for:

• Players pressing/defending
• Players about to receive
• Physical closeness regardless of possession

---

Combined Spatial Examples

Player attacking in final third

{
  "operator": "AND",
  "filters": [
    {
      "type": "player_ball_proximity",
      "players": ["0-10"],
      "threshold": 5
    },
    {
      "type": "ball_location",
      "x_min": 70,
      "x_max": 105
    }
  ]
}

Defensive actions

Find goalkeeper and defenders near ball in own third:

{
  "operator": "AND",
  "filters": [
    {
      "type": "player_ball_proximity",
      "players": ["0-1", "0-4", "0-5", "0-6"],
      "threshold": 5
    },
    {
      "type": "ball_location",
      "x_min": 0,
      "x_max": 35
    }
  ]
}