Skip to content

API v1 Overview

API version 1 provides comprehensive access to football match analysis data.

Base URL

https://aiontheball.nl/api/v1/

Available Endpoints

Video Management

Endpoint Method Description
/videos GET List all videos
/videos POST Upload a new video
/videos/{id} GET Get video details and status
/videos/{id} PUT Update video metadata
/videos/{id}/analysis POST Create analysis for a video

Analysis Data

Endpoint Method Description
/analyses/{id} GET Get analysis details and status
/analyses/{id}/events GET Get all detected events
/analyses/{id}/summary GET Get comprehensive game summary with player identities
/analyses/{id}/query-intervals POST Query time intervals with filters
/analyses/{id}/tracking/download GET Download raw tracking data
/analyses/{id}/schema GET Get the engine schema (event types and metadata fields)
/analyses/{id}/exemplar-crops GET List and fetch exemplar crop images for players/teams

Response Format

All endpoints return JSON. Successful responses have HTTP status 200.

The video and analysis management endpoints (/videos/*, GET /analyses/{id}) wrap their payload in a data envelope, with a message on errors:

{
  "data": { ... }
}

{
  "message": "Analysis not found"
}

The analysis results endpoints (/analyses/{id}/events, /summary, /query-intervals, /schema, /tracking/download) return their payload unwrapped — a bare JSON array or object, as shown on each endpoint page — and report errors with a detail field:

{
  "detail": "Analysis not found"
}

Rate Limits

  • 100 requests per minute per API token
  • Tracking downloads: 10 per hour

Capabilities

Event Detection

  • Team possession changes
  • Player possession
  • Match timeline (halves)
  • Scene classification (play vs replay)

Player Tracking

  • Position data at 25 FPS
  • Player identification by jersey number
  • Distance and speed calculations

Filtering

  • Combine multiple conditions with AND/OR
  • Filter by location, possession, time, and more
  • Generate highlight clips