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
running Processing video
aggregating Combining results
done Complete
error Failed

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:

{
  "possession": {
    "team_0": 0.52,
    "team_1": 0.48
  },
  "player_stats": {
    "0-10": {
      "distance_m": 10542,
      "top_speed_kmh": 28.5
    }
  },
  "identities": {
    "0-10": "Team A #10",
    "1-7": "Team B #7"
  }
}

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:

{
  "data": [
    {
      "type": "possession_change",
      "timestamp": 125.4,
      "team": "team_0",
      "player_id": "0-10"
    }
  ]
}

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?