Events

Retrieve all detected events in an analysis.

Request

GET /analyses/{id}/events

Response

[
  {
    "start": 0.04,
    "end": 20.36,
    "label": "Team A",
    "event_type": "team_possession"
  },
  {
    "start": 20.40,
    "end": 45.80,
    "label": "Team B",
    "event_type": "team_possession"
  },
  {
    "start": 0.00,
    "end": 3.00,
    "label": "not analysable",
    "event_type": "scene"
  },
  {
    "start": 3.04,
    "end": 2700.00,
    "label": "analysable",
    "event_type": "scene"
  },
  {
    "start": 0.00,
    "end": 5400.00,
    "label": "full_game",
    "event_type": "match_timeline"
  },
  {
    "start": 617.92,
    "end": 617.92,
    "label": "pass",
    "event_type": "pass"
  },
  {
    "start": 633.48,
    "end": 633.48,
    "label": "drive",
    "event_type": "drive"
  },
  {
    "start": 664.16,
    "end": 664.16,
    "label": "shot",
    "event_type": "shot"
  },
  {
    "start": 700.20,
    "end": 700.20,
    "label": "tackle",
    "event_type": "tackle"
  },
  {
    "start": 0.04,
    "end": 617.88,
    "label": "in_play",
    "event_type": "ball_phase"
  }
]

Response Fields

Field	Type	Description
start	float	Start time in seconds
end	float	End time in seconds
label	string	Human-readable label
event_type	string	Type of event

Event Types

Type	Description	Labels
team_possession	Which team has the ball	Team names
player_possession	Which player has the ball	Player ID or name
scene	Whether footage is analysable	analysable, not analysable
match_timeline	Game period	first_half, second_half, full_game
pass	Pass action detected	Action type name
drive	Dribble action detected	Action type name
shot	Shot action detected	Action type name
tackle	Tackle action detected	Action type name
block	Block action detected	Action type name
ball_phase	Ball in/out of play state	Phase value (e.g., in_play, out_of_bounds)

Data Version Availability

Ball action events (pass, drive, shot) are available from data version 2+. Additional actions (tackle, block) and ball_phase are available from data version 3+.

Understanding Events

Team Possession Events

Continuous periods where a team controls the ball. Gaps between events may indicate:

• Ball out of play
• Unclear possession
• Transition moments

Scene Events

Classify video segments:

• Analysable: Actual gameplay footage
• Not analysable: Replays, crowd shots, graphics, half-time

Timeline Events

Mark game periods. full_game spans the entire video, while half events mark specific periods if detected.

Ball Action Events

These events capture specific on-ball actions. The label is set to the action type name (e.g., pass, drive, shot, tackle, block).

Pass Events (pass)

Detected when a player passes the ball to a teammate. Each pass event includes:

• Timing: The moment the pass is made (start and end are typically the same timestamp)
• Label: Action type name (pass)

Drive Events (drive)

Detected when a player dribbles with the ball. Each drive event includes:

• Timing: Duration of the dribble action
• Label: Action type name (drive)

Shot Events (shot)

Detected when a player takes a shot on goal. Each shot event includes:

• Timing: The moment the shot is taken
• Label: Action type name (shot)

Tackle Events (tackle)

Detected when a player makes a tackle. Each tackle event includes:

• Timing: The moment the tackle occurs
• Label: Action type name (tackle)

Block Events (block)

Detected when a player blocks the ball. Each block event includes:

• Timing: The moment the block occurs
• Label: Action type name (block)

Filtering Ball Actions

Use the ball_action filter with the Query Intervals endpoint to find specific actions by player or team.

Ball Phase Events

Ball phase events indicate whether the ball is in play or out of play. The label is set to the phase value.

Possible phase values:

• in_play: Ball is actively in play
• out_of_bounds: Ball has gone out of bounds
• in_bounds_stoppage: Ball is within the field but play is stopped (e.g., foul, injury)
• half_kickoff: Period around a half kickoff

Example

cURLPython

curl -X GET "https://aiontheball.nl/api/v1/analyses/1246/events" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

import requests

response = requests.get(
    'https://aiontheball.nl/api/v1/analyses/1246/events',
    headers={'Authorization': f'Bearer {token}'}
)
events = response.json()

# Filter by event type
possession_events = [e for e in events if e['event_type'] == 'team_possession']

# Calculate total possession time per team
from collections import defaultdict
possession_time = defaultdict(float)
for event in possession_events:
    possession_time[event['label']] += event['end'] - event['start']

# Get ball action events
passes = [e for e in events if e['event_type'] == 'pass']
shots = [e for e in events if e['event_type'] == 'shot']
dribbles = [e for e in events if e['event_type'] == 'drive']

print(f"Total passes: {len(passes)}")
print(f"Total shots: {len(shots)}")
print(f"Total dribbles: {len(dribbles)}")