Schema

Retrieve the event schema for an analysis — available event types, their metadata properties, available filters, and frame_state availability.

Use this endpoint to discover capabilities

Different analyses may have different data versions. Query the schema to know which event types, properties, and filters are available before building queries.

Request

GET /analyses/{id}/schema

Response

Data Version 3+

{
  "data_version": 3,
  "engine_version": "latest",
  "event_types": {
    "pass": {
      "summary": "A deliberate attempt to deliver the ball to a teammate....",
      "properties": [
        { "name": "body_part", "type": "str", "enum": ["head", "both_hands", "unknown"] },
        { "name": "confidence_detection", "type": "float32" },
        { "name": "confidence_event", "type": "float32" }
      ]
    },
    "shot": {
      "summary": "An attempt to score: a kick or other body contact...",
      "properties": [
        { "name": "body_part", "type": "str", "enum": ["head", "both_hands", "unknown"] },
        { "name": "confidence_detection", "type": "float32" },
        { "name": "confidence_event", "type": "float32" }
      ]
    },
    "tackle": {
      "summary": "A defensive challenge that legally dispossesses the...",
      "properties": [
        { "name": "body_part", "type": "str", "enum": ["head", "both_hands", "unknown"] },
        { "name": "confidence_detection", "type": "float32" },
        { "name": "confidence_event", "type": "float32" }
      ]
    }
  },
  "filters": [
    { "type": "team_possession", "description": "..." },
    { "type": "event_property", "description": "..." },
    { "type": "frame_state", "description": "..." }
  ],
  "frame_state": {
    "available": true,
    "columns": [
      { "name": "timestamp", "type": "int32", "description": "Milliseconds from match start; join key. Same..." },
      { "name": "player_id", "type": "str", "description": "Identity-resolved 'team-jersey' id; join key." },
      { "name": "speed_mps", "type": "float32", "description": "Smoothed speed in m/s — Savitzky-Golay..." }
    ]
  }
}

Data Version 1/2

Older analyses return a minimal schema with no event type details:

{
  "data_version": 2,
  "engine_version": "0.5.10",
  "event_types": {},
  "filters": [
    { "type": "team_possession", "description": "..." },
    { "type": "ball_action", "description": "..." }
  ],
  "frame_state": {
    "available": false,
    "columns": []
  }
}

Response Fields

Field	Type	Description
data_version	integer	Event data version (1, 2, or 3)
engine_version	string	Engine version that produced the data
event_types	object	Map of event type name → definition (empty for v1/v2)
event_types[].summary	string	Human-readable description
event_types[].properties	array	Available metadata properties for this event type
filters	array	All available filter types
frame_state.available	boolean	Whether frame_state data exists
frame_state.columns	array	Available frame_state columns

Example

cURLPython

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

import requests

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

# Check data version
print(f"Data version: {schema['data_version']}")

# List available event types
for name, evt in schema['event_types'].items():
    print(f"  {name}: {evt['summary'][:60]}")

# Check frame_state availability
if schema['frame_state']['available']:
    for col in schema['frame_state']['columns']:
        print(f"  frame_state: {col['name']} ({col['type']})")