AIB Insight API
HTTP API for football match analysis. Upload a video, run an analysis over it, then read back events, tracking, summaries and per-player and per-team match reports.
Base URL
https://aiontheball.nl/api/v1/
Every request carries a bearer token. See Authentication.
Versions
| Version | Status | Released |
|---|---|---|
| v1 | Current | 2025-12 |
Services
Two services answer under one base URL and one token. They differ in response envelope, see Response format.
| Service | Paths | Covers |
|---|---|---|
| Hub | /videos/*, GET /analyses/{id} |
Video upload, team identity, analysis creation and status |
| Insight | The result paths under /analyses/{id}/ |
Events, summary, reports, interval queries, tracking |
Endpoints
Hub:
| Endpoint | Description |
|---|---|
/videos |
List videos, or create one from a public URL |
/videos/{id} |
Read, update or delete one video and its status |
/videos/{id}/preview-teams |
Kit colours and player crops detected before analysis |
/videos/{id}/meta |
Read the resolved game-meta envelope |
/videos/{id}/embed-token |
Mint a token for the confirm-sides widget |
/videos/{id}/analysis |
Create an analysis for a video |
/analyses/{id} |
Analysis status, progress and quality |
/analyses/{id}/team-mapping |
Resolve team_0 / team_1 to home/away, names and squads |
Insight:
| Endpoint | Description |
|---|---|
/analyses/{id}/events |
Every detected event, as timed rows |
/analyses/{id}/summary |
Match summary: possession, player identities and player statistics |
/analyses/{id}/player-report/{player_id} |
Per-player report: coverage, physical, position, on-ball, interactions |
/analyses/{id}/team-report |
Per-team report: average positions, possession, territory, kits, quality |
/analyses/{id}/query-intervals |
Time intervals matching a filter query |
/analyses/{id}/tracking/download |
Raw player and ball positions as Parquet or JSON |
/analyses/{id}/schema |
Event types and metadata fields the analysis carries |
/analyses/{id}/exemplar-crops |
Player and team appearance crops |
Reading order
- API v1 Overview for the endpoint list, response format and rate limits.
- Authentication for the header and its error responses.
- Analysis Workflow for the order of calls from upload to results. An analysis takes 2 to 6 hours, depending on video length and queue size.
- Concepts for teams and sides, pitch coordinates, player ids, possession, and speed and distance.
- The endpoint page for each response, field by field.
- Changelog for what changed per release.
Contact support@smart11.ai for tokens and support.