Athlemetrics API

An API for player ratings and role clustering built on per‑90 match data—designed for leaderboards, scouting filters, and model evaluation.

30k+

Training player samples

0–10 / 0–100

Score display scales

Base · DB · Role

Core modules

▶ Quickstart OpenAPI Endpoints Model Gallery

Website About Us Rating Analysis Role Analysis

Base score: predicted vs actual — Base score · Predicted vs actual

Rating model: GroupKFold R2 — Rating model · GroupKFold R²

Role clustering: UMAP — Role clustering · UMAP visualization

Core Modules

Base Score (Rating Prediction)

Use kit_name + payload as input to return a score and a module breakdown for comparison and explanation.

Key endpoints: /base-score/predict · /base-score/slider-params

Database (Dataset Query)

Fetch historical records with scores using filters and pagination—built for leaderboards, filtering, and backtesting.

Key endpoint: /database/base-score/dataset

Player Role (Clustering)

Cluster players by style: legend explains labels, search retrieves players, and predict supports custom inputs.

Key endpoints: /role-cluster/search · /role-cluster/predict/custom

Data & Model Results (from assets/img)

Base Score Model

train_test_metrics — Train/test metric summary

More details: Rating analysis.

Player Role Clustering

More details: Role analysis.

Endpoint Explorer (from OpenAPI)

Method	Path	Description	Tag

Quickstart (3+2 steps)

1) Configure & health check

export BASE_URL="https://your-host/v1"
export API_KEY="xxxxx" # optional

curl -s "$BASE_URL/health" \
  -H "x-api-key: $API_KEY"

If you use gateway auth, add your API key header. For CORS checks, use /test-cors.

2) Discover kits (input templates)

curl -s "$BASE_URL/base-score/kits" | jq '.[0]'
# Fields: kit_name, aliases, score_scale, model_type, modules

A kit defines required input aliases and scoring modules (often aligned with positions/roles).

3) Predict base score (with explanations)

curl -s "$BASE_URL/base-score/predict" \
  -H "Content-Type: application/json" \
  -d '{
    "kit_name": "attacker_core",
    "model_type": "gb",
    "score_scale": "0-10",
    "show_features": true,
    "payload": {
      "shots_total_p90": 2.8,
      "xg_p90": 0.35,
      "pressures_p90": 10.2
    }
  }' | jq '{score: .score, breakdown: .modules[0:2]}'

Switch score_scale between 0–10 and 0–100; enable show_features for interpretability.

4) Role clustering: legend + search

curl -s "$BASE_URL/role-cluster/legend" | jq '.[0]'

curl -s "$BASE_URL/role-cluster/search?query=benzema&limit=5"

legend explains labels and sample counts; search supports fuzzy queries and returns role/team/league.

5) Query dataset with pagination

curl -s "$BASE_URL/database/base-score/dataset?page=1&page_size=20" \
  -G --data-urlencode "season=2023/2024" \
     --data-urlencode "league=EPL" \
     --data-urlencode "position=FW"

Use the output for leaderboards or visualization; pair it with the charts below for model performance context.

Charts & Platform UI

Base Score Charts

feature_importances — Feature importance

Add a short takeaway with a key metric (e.g., R², error range).

Player Role Charts

label_position_heatmap — Role vs position heatmap

Use these to communicate label distribution and interpretability alongside search/predict.

API Platform Screenshot

API platform UI — Kit selection, slider ranges, predicted score, and breakdown

Note: These pages share the same UI theme (assets/css/athlemetrics_ui.css / assets/js/athlemetrics_ui.js). Click any chart to zoom (Esc to close, ←/→ to navigate).