Skip to content

AIB Insight API Documentation

Welcome to the AI on the Ball (AIB) Insight API documentation. This API provides access to advanced football/soccer match analysis including player tracking, possession analysis, and tactical insights.

Current Version

Version Status Released
v1 Current 2025-12

Base URL

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

Authentication

All endpoints require a Bearer token in the Authorization header. Contact support@smart11.ai to obtain your API token.

Authorization: Bearer YOUR_API_TOKEN

See Authentication for more details.

Quick Start

This guide walks you through the complete workflow: uploading a video, creating an analysis, and retrieving results.

Step 1: Upload a Video

First, create a video by providing a public URL to your match footage.

curl -X POST "https://aiontheball.nl/api/v1/videos" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "video_file_url": "https://your-storage.com/match.mp4",
    "title": "Team A vs Team B",
    "home_team_name": "Team A",
    "away_team_name": "Team B",
    "left_start_team": "home"
  }'

Only video_file_url is required. Filling home-, away-team names and left_start_team will change the labels in the query engine and summary.

Response:

{
  "data": {
    "id": 789,
    "status": "created",
    "game_name": "swift-eagle-43",
    "title": "Team A vs Team B",
    "created_at": "2025-02-08T10:00:00Z"
  }
}

See Videos for all video options and status values.

Step 2: Create an Analysis

Create an analysis for your video.

curl -X POST "https://aiontheball.nl/api/v1/videos/789/analysis" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Response:

{
  "data": {
    "id": 1247,
    "video_id": 789,
    "status": "init",
    "progress": 0,
    "results_available": false
  }
}

See Create Analysis for FPS options and requirements.

Step 3: Monitor Progress

Poll the analysis endpoint to track progress. Analysis typically takes 2 to 6 hours depending on video length and queue size.

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

Response (in progress):

{
  "data": {
    "id": 1247,
    "status": "running",
    "progress": 45,
    "results_available": false
  }
}

Response (complete):

{
  "data": {
    "id": 1247,
    "status": "done",
    "progress": 100,
    "results_available": true,
    "aggregate_version": "0.4.98"
  }
}
Status Meaning
init Initializing
waiting_for_video Waiting for video
running Processing video
done Complete
error Failed
ignored Will not be processed
no_match_detected No soccer match detected
needs_attention Pending manual review

See Get Analysis for full response details.

Webhooks can be configured to receive real-time notifications of updated completion rates and final analysis completion. See Webhooks.

Step 4: Get Results

Once status is done, fetch the analysis data.

Get Game Summary

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

Response:

{
  "metadata": { "game_id": "2025-01-15_hub-1246", "video_length_sec": 5425.5 },
  "teams": { "team_0_name": "Team A", "team_1_name": "Team B" },
  "match_stats": { "analysable_duration_sec": 5320.0 },
  "possession": {
    "summary": {
      "team_0": { "seconds": 2750.5, "pct": 52.1 },
      "team_1": { "seconds": 2120.0, "pct": 40.2 },
      "unknown": { "seconds": 410.0, "pct": 7.7 }
    },
    "per_minute": [
      { "minute": 0, "team_0_pct": 58.67, "team_1_pct": 33.5, "unknown_pct": 7.83 }
    ]
  },
  "players": [
    {
      "player_id": "0-10",
      "team_id": "team_0",
      "name": "Team A #10",
      "stats": { "total_distance_m": 10542.5, "max_speed_kmh": 32.1 }
    }
  ]
}

(truncated — see the endpoint page for the full structure)

See Summary for all available statistics.

Get Events

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

Response:

[
  {
    "start": 125.5,
    "end": 135.5,
    "label": "Team A",
    "event_type": "team_possession"
  },
  {
    "start": 130.1,
    "end": 131.4,
    "label": "pass",
    "event_type": "pass"
  }
]

See Events for event types.

Query Specific Moments

Find all moments when the ball was in the opponent's penalty area:

curl -X POST "https://aiontheball.nl/api/v1/analyses/1247/query-intervals" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      {"type": "ball_location", "x_min": 88.5}
    ]
  }'

See Query Intervals and Filters for advanced queries.

Download Tracking Data

Get raw position data for all players and the ball at 25 FPS:

curl -X GET "https://aiontheball.nl/api/v1/analyses/1247/tracking/download?format=parquet" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -o tracking.parquet

See Tracking for data schema and format options.

Complete Python Example

import time
import requests

API_URL = "https://aiontheball.nl/api/v1"
TOKEN = "YOUR_API_TOKEN"
headers = {"Authorization": f"Bearer {TOKEN}"}

# 1. Create video
video = requests.post(f"{API_URL}/videos", headers=headers, json={
    "video_file_url": "https://your-storage.com/match.mp4",
    "title": "Team A vs Team B"
}).json()["data"]

# 2. Create analysis
analysis = requests.post(
    f"{API_URL}/videos/{video['id']}/analysis", headers=headers, json={}
).json()["data"]

# 3. Wait for analysis (typically 2-6 hours)
while analysis["status"] != "done":
    time.sleep(60)
    analysis = requests.get(f"{API_URL}/analyses/{analysis['id']}", headers=headers).json()["data"]
    print(f"Progress: {analysis.get('progress', 0)}%")

# 4. Get results
summary = requests.get(f"{API_URL}/analyses/{analysis['id']}/summary", headers=headers).json()
print(f"Possession: {summary['possession']}")

# 5. Download tracking data
tracking = requests.get(
    f"{API_URL}/analyses/{analysis['id']}/tracking/download",
    headers=headers, params={"format": "parquet"}
)
with open("tracking.parquet", "wb") as f:
    f.write(tracking.content)

Need Help?