The current public surface consists of:

• A family of rating models, accessed via the base-score endpoints.
• A family of role-cluster models, accessed via the role-cluster endpoints.

1. System Overview

At a high level, Athlemetrics is organized around two complementary tasks:

1. Quantifying Performance

Using supervised models to map per-90 seasonal statistics to a continuous base score, calibrated within role.

2. Describing Playing Style

Using clustering and ensemble methods to assign players to data-driven roles (e.g. crossing fullback, balanced midfielder, pressing defender), rather than relying only on nominal positions.

These components are exposed via an API-first architecture:

• Model metadata and feature definitions are available via dedicated endpoints.
• Predictions are obtained through a small number of HTTP endpoints, with JSON payloads.
• The same backend serves both the internal platform UI and external consumers.

This design allows Athlemetrics to be embedded in club dashboards, research notebooks, scouting workflows or other applications without re-implementing the modelling pipeline.

2. Rating Models (/base-score/...)

The rating component of Athlemetrics is responsible for answering a structured version of a common question:

Given this player’s season statistics, how strong was the season relative to professional players in a similar role?

To achieve this, the rating pipeline is built around several principles.

2.1 Role-specific Feature Sets (Kits)

Inputs are organized into kits, which represent broad functional groups such as attackers, midfielders, defenders and goalkeepers. Each kit has:

• A defined set of expected input features (for example, goals per 90, xG per 90, assists per 90, duels per 90, cards per 90).
• Role-aware engineered features (ratios and rates that behave differently for different parts of the pitch).

The endpoint GET /base-score/kits provides the list of available kits, and GET /base-score/model-features describes which features are expected for each combination of kit and model.

2.2 Per-90 Normalization

All rating models operate on per-90 statistics, rather than raw totals. This avoids trivial scaling effects where players with more minutes always appear stronger.

In practical terms, data pipelines are expected to compute values such as:

• goals per 90
• xG per 90
• assists per 90
• pressures per 90
• yellow cards per 90

before calling the prediction endpoint. This keeps the core model focused on comparing profiles rather than minutes played.

2.3 Trained Models Behind a Single Prediction Interface

The central endpoint for ratings is:

Accepts a kit, a model identifier and a feature payload; returns a prediction including the base score and related fields.

Supporting endpoints allow clients to discover what is available:

Lists available rating models (e.g. different algorithms or training runs).

Describes which features each model expects for each kit.

This approach keeps the prediction surface stable, while allowing the underlying models to be iterated and extended.

2.4 Score Scaling and Quantiles

The raw outputs of the models are tailored for training rather than direct UI consumption. To support visualization and downstream use, Athlemetrics exposes:

Returns calibrated bounds for model scores, based on training distributions.

Returns quantile information for individual features.

Provides suggested ranges for interactive sliders in user interfaces.

These endpoints allow front-ends and tools to:

• Map model outputs into interpretable ranges (e.g. 0–10 or 0–100).
• Build reasonable input controls that reflect how real players are distributed.
• Keep UI behaviour consistent with the data used during model training.

3. Role-Cluster Models (/role-cluster/...)

While rating models focus on “how strong was this season?”, the role-cluster component focuses on “what type of player profile does this look like?”.

3.1 Data-driven Roles

The clustering pipeline groups players into roles based on feature patterns rather than nominal positions. Examples include:

• Balanced midfielders
• Crossing fullbacks
• Pressing defenders
• Attacking/creative hybrids

These roles are the result of ensemble clustering over seasonal feature vectors, followed by a human-readable naming step.

3.2 Role-cluster Endpoints

The role-cluster API exposes several capabilities:

Lists available label sources (e.g. different clustering runs or ensemble definitions).

Provides the mapping between cluster identifiers and role names, alongside basic statistics such as cluster sizes.

Searches the internal role dataset (e.g. by player, team or other filters, depending on the backing data configuration) and returns matching records and their identifiers.

Returns the role prediction and associated information for a specific record in the dataset.

Accepts a custom feature payload and returns the predicted role for that hypothetical or external player profile.

Together, these endpoints make it possible to:

• Compare players within the same playing-style cluster.
• Track role changes over time within a squad.
• Use role labels as features in separate models (for example, for valuation, ageing curves or tactical fit).

4. API-first Design and Infrastructure Endpoints

Athlemetrics is built as an API-first project. The internal platform (for example, the UI hosted under the platform subdomain) is essentially one of many possible clients of the same API.

Several endpoints are dedicated to infrastructure and tooling:

Lightweight health check for monitoring and basic connectivity tests.

Endpoint for verifying CORS behaviour in browser-based clients.

Surface information about the status of backing datasets.

Surface information useful for visualization modules that depend on pre-computed chart data.

This separation allows:

• Programmatic health checks and alerting.
• Safer integration from browser-based tools.
• Clear distinction between modelling logic and platform/UI concerns.

The API is defined via an OpenAPI 3.1 schema, which can be used to generate client libraries or interactive documentation views if needed.

5. Typical Usage Scenarios

Because Athlemetrics focuses on being a reusable analytics layer, it is suited to a range of users who already have access to football data.

5.1 Clubs, Analysts and Scouts

• Benchmark players on a consistent rating scale within role.
• Explore how potential signings compare to existing squad members in both rating and role.
• Monitor role shifts (e.g. fullback to inverted midfielder) and the associated changes in ratings.

5.2 Researchers and Students

• Use the rating and role outputs as a stable backbone when studying methodological questions (sample bias, model comparison, causal inference).
• Combine Athlemetrics outputs with external data (e.g. salary, age, tracking information) for more complex analyses. A sample dataset with predictions is available for exploration and experimentation.

5.3 Builders and Product Teams

• Embed player evaluation into internal tools, dashboards or public-facing applications. The API is accessible via RapidAPI for easy integration and testing.
• Integrate the API into larger AI workflows that need structured, model-based views of player quality and style.

In all cases, Athlemetrics outputs should be interpreted as structured estimates, derived from a specific dataset and modelling pipeline, rather than ground truth. For decisions with financial or sporting consequences, they are best used as one input among many.

6. Roadmap and Future Work

The current version of Athlemetrics focuses on robust core models and a clean API surface. Planned directions include:

Expanded Public Ratings

Making per-season ratings for real players available via dedicated endpoints, reducing the need to manually construct feature payloads for every query.

Helper Tools and Calculators

Providing simple flows for converting raw match totals into the per-90 features expected by the models, including CSV-based workflows.

Broader Data Coverage and Model Iteration

Extending the number of competitions and seasons covered, refining role definitions, and improving score calibration as new data becomes available.

Applied Examples and Case Studies

Publishing concise examples and notebooks that demonstrate how to use the API in realistic scenarios (recruitment, squad analysis, research projects, and so on). A collection of practical examples is available to help you get started quickly.

Athlemetrics is intended to act as a reliable, reusable spine for football analytics work built on top of existing data sources. By keeping the interface narrow and the models transparent, it aims to make structured player evaluation and role analysis accessible to a broader range of users and projects.