Football Performance API Documentation — Futrix Metrics

Complete reference guide for the Futrix Metrics Football Performance API. Score and predict football player performance, query player ratings, generate scouting reports, and access role-cluster analytics.

Football Performance API Documentation

Futrix Metrics — Intelligent football analytics at scale. Learn more about us · Get API Access

The Futrix Metrics Football Performance API gives you programmatic access to football player ratings, performance predictions, role-cluster analytics, scouting reports, and model visualisation charts — all through a single REST interface.

Built for analysts, scouts, and developers who need reliable, model-driven football data. See how it’s used in our Player Rating & Cluster project and development notes.

Overview
Base URL
Authentication
Get API Access
Pagination
Endpoints
Data Models & Schemas
- PredictRequest
- HTTPValidationError
Error Reference
Quick Start Examples
Feature Reference

Overview

The Futrix Metrics Football Performance API is a RESTful API that returns JSON responses (or HTML for the /report endpoint). All requests are authenticated and rate-limited based on your subscription plan.

Property	Value
API Version	`1.0.0`
Protocol	HTTPS
Request format	`application/json`
Response format	`application/json` (HTML for `/report`)
Authentication	API Key (`X-API-Key` header)

Want to understand the models powering this API? Read about the Player Rating & Cluster methodology and explore the full development background.

Base URL

https://footballperformanceapi.site

All endpoint paths in this documentation are relative to the base URL. For example:

GET https://footballperformanceapi.site/database/ratings

Authentication

All API endpoints (except GET /health) require an API key passed via the X-API-Key request header.

X-API-Key: <your_api_key>

Example:

curl -H "X-API-Key: <your_api_key>" \
  https://footballperformanceapi.site/database/ratings

Your API key is issued when you subscribe to a plan. Keep it private and never expose it in client-side code or public repositories.

Get API Access

To obtain an API key, visit www.futrixmetrics.com/services to explore available plans, try the API, or request access.

Not sure which plan fits your use case? Learn more about Futrix Metrics or browse our open projects to see the API in action.

Pagination

All Database endpoints support offset-based pagination via limit and offset query parameters.

Parameter	Type	Default	Max	Description
`limit`	integer	`200`	`5000`	Maximum rows to return
`offset`	integer	`0`	—	Number of rows to skip

Example — page 2 with 100 rows per page:

GET /database/ratings?limit=100&offset=100

For large datasets, iterate through pages by incrementing offset by limit until fewer rows than limit are returned.

Endpoints

Database

The Database endpoints expose raw access to the Futrix Metrics player ratings and role-clustering tables. All database endpoints use GET and support filtering by multiple parameters.

To understand what these ratings represent, see the Player Rating & Cluster project.

`GET /database/ratings`

Retrieve player ratings records. Supports filtering by player, season, league, and team.

Authentication: X-API-Key — see Authentication

Query Parameters

Parameter	Type	Required	Description
`player_id`	integer	No	Filter by numeric player ID
`full_name`	string	No	Filter by player full name (exact match)
`season`	string	No	Filter by season string, e.g. `2024/2025`
`league`	string	No	Filter by league name (exact match)
`team`	string	No	Filter by team name (exact match)
`limit`	integer	No	Max rows to return (1–5000, default `200`)
`offset`	integer	No	Row offset for pagination (default `0`)

Example Request

curl -H "X-API-Key: <your_key>" \
  "https://footballperformanceapi.site/database/ratings?league=Premier%20League&season=2024%2F2025&limit=50"

Response

200 OK
Content-Type: application/json

{
  "data": [ ... ]
}

`GET /database/role-cluster-results`

Retrieve role-cluster classification results for individual players. Each record maps a player to a cluster identity across one or more clustering dimensions.

Authentication: X-API-Key — see Authentication

Query Parameters

Parameter	Type	Required	Description
`player_id`	integer	No	Filter by numeric player ID
`player_name`	string	No	Filter by player name (exact match)
`season`	string	No	Filter by season (exact match)
`league`	string	No	Filter by league (exact match)
`club`	string	No	Filter by club name (exact match)
`position`	string	No	Filter by position (exact match)
`source`	string	No	Filter by data source (exact match)
`cluster_id`	integer	No	Filter by numeric cluster ID
`cluster_group`	string	No	Filter by cluster group label
`cluster_local`	string	No	Filter by local cluster label
`cluster_name`	string	No	Filter by cluster display name
`limit`	integer	No	Max rows (1–5000, default `200`)
`offset`	integer	No	Row offset (default `0`)

Example Request

curl -H "X-API-Key: <your_key>" \
  "https://footballperformanceapi.site/database/role-cluster-results?position=midfielder&season=2024%2F2025"

Response

200 OK
Content-Type: application/json

{
  "data": [ ... ]
}

Related: Role Cluster Summary · Ratings · Cluster methodology

`GET /database/role-cluster-summary`

Retrieve aggregated summary data for each role cluster. Use this endpoint to understand the characteristics and metadata of each cluster group without fetching individual player records.

Authentication: X-API-Key — see Authentication

Query Parameters

Parameter	Type	Required	Description
`cluster_id`	integer	No	Filter by numeric cluster ID
`cluster_group`	string	No	Filter by cluster group label
`cluster_local`	string	No	Filter by local cluster label
`cluster_name`	string	No	Filter by cluster display name
`limit`	integer	No	Max rows (1–5000, default `200`)
`offset`	integer	No	Row offset (default `0`)

Example Request

curl -H "X-API-Key: <your_key>" \
  "https://footballperformanceapi.site/database/role-cluster-summary?cluster_group=attacker"

Response

200 OK
Content-Type: application/json

{
  "data": [ ... ]
}

Score & Prediction

The Score endpoints expose the Futrix Metrics machine-learning prediction models. Submit a player’s raw statistics as a feature vector and receive a predicted performance score in return.

Read about how the scoring models were built at futrixmetrics.com/project/develop.

See the PredictRequest schema for the full list of supported feature fields.

`GET /score/`

Health and status check for the Score service. Returns service metadata.

Authentication: X-API-Key — see Authentication

Example Request

curl -H "X-API-Key: <your_key>" \
  https://footballperformanceapi.site/score/

Response

200 OK
Content-Type: application/json

{ ... }

`POST /score/predict`

Submit a player’s statistics and receive a Pro model performance score prediction. This endpoint uses the full Futrix Metrics model ensemble.

Authentication: X-API-Key — see Authentication

Request Body — application/json — PredictRequest

Field	Type	Required	Description
`features`	object	Yes	Key/value map of player statistics — see feature list

Example Request

curl -X POST \
  -H "X-API-Key: <your_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "features": {
      "player_name": "Example Player",
      "position": "defender",
      "league": "Premier League",
      "club": "Example FC",
      "season": "2024/2025",
      "minutes": 1980,
      "goals": 3,
      "assists": 5,
      "passes_attempted": 1900,
      "passes_completed": 1650,
      "tackles": 68,
      "tackles_won": 45,
      "interceptions": 52,
      "clearances": 140,
      "blocks": 35,
      "shots": 28,
      "shots_on_target": 10,
      "dribbles": 42,
      "dribbles_successful": 23,
      "aerials": 90,
      "aerials_won": 56,
      "fouls_committed": 22,
      "fouls_drawn": 18,
      "yellow_cards": 4,
      "red_cards": 0
    }
  }' \
  https://footballperformanceapi.site/score/predict

Response

200 OK
Content-Type: application/json

{ ... }

`POST /score/predict-base`

Submit a player’s statistics and receive a Base model performance score prediction. Useful for comparing predictions against the full Pro model from POST /score/predict.

Authentication: X-API-Key — see Authentication

Request Body — application/json — PredictRequest

Identical request body to POST /score/predict. See the PredictRequest schema for the full field list.

Example Request

curl -X POST \
  -H "X-API-Key: <your_key>" \
  -H "Content-Type: application/json" \
  -d '{ "features": { ... } }' \
  https://footballperformanceapi.site/score/predict-base

Response

200 OK
Content-Type: application/json

{ ... }

Charts & Visualisation

The Charts endpoints return data for visualising model performance, feature importance, position distributions, and league coverage. These are ideal for building internal dashboards or embedding analytics in your application.

`GET /charts/overview`

Returns a high-level overview of model coverage and performance statistics.

Authentication: X-API-Key — see Authentication

Example Request

curl -H "X-API-Key: <your_key>" \
  https://footballperformanceapi.site/charts/overview

Related: Positions chart · Leagues chart · Feature chart

`GET /charts/positions`

Returns distribution data for the top N player positions in the dataset. Use this to understand model coverage across positions.

Authentication: X-API-Key — see Authentication

Query Parameters

Parameter	Type	Required	Default	Max	Description
`limit`	integer	No	`20`	`100`	Top N positions to return

Example Request

curl -H "X-API-Key: <your_key>" \
  "https://footballperformanceapi.site/charts/positions?limit=10"

Related: Leagues chart · Overview chart

`GET /charts/leagues`

Returns distribution data for the top N leagues in the dataset. Use this to understand the geographic and competition-level coverage of the model.

Authentication: X-API-Key — see Authentication

Query Parameters

Parameter	Type	Required	Default	Max	Description
`limit`	integer	No	`20`	`100`	Top N leagues to return

Example Request

curl -H "X-API-Key: <your_key>" \
  "https://footballperformanceapi.site/charts/leagues?limit=30"

Related: Positions chart · Ratings database

`GET /charts/models/base`

Returns performance metrics and chart data for the Base prediction model.

Authentication: X-API-Key — see Authentication

Example Request

curl -H "X-API-Key: <your_key>" \
  https://footballperformanceapi.site/charts/models/base

Related: Pro model charts · Predict Base · Model development

`GET /charts/models/pro`

Returns performance metrics and chart data for the Pro prediction model.

Authentication: X-API-Key — see Authentication

Example Request

curl -H "X-API-Key: <your_key>" \
  https://footballperformanceapi.site/charts/models/pro

Related: Base model charts · Predict (Pro) · Model development

`GET /charts/features`

Returns the top N features by usage difference between the Base and Pro models. Use this to understand which statistics drive the most differentiation in the Pro model.

Authentication: X-API-Key — see Authentication

Query Parameters

Parameter	Type	Required	Default	Max	Description
`top`	integer	No	`30`	`200`	Top N features to return by usage difference

Example Request

curl -H "X-API-Key: <your_key>" \
  "https://footballperformanceapi.site/charts/features?top=50"

Related: PredictRequest feature list · Base model · Pro model

Reports

`GET /report`

Generate a full HTML scouting report for a player. This endpoint returns a rendered HTML document rather than JSON, making it suitable for embedding in web pages or saving as a standalone report file.

Authentication: X-API-Key — see Authentication

Query Parameters

Parameter	Type	Required	Description
`player_id`	integer	No	Lookup player by numeric ID
`name`	string	No	Lookup player by name
`season`	string	No	Filter report to a specific season
`league`	string	No	Filter report to a specific league
`team`	string	No	Filter report to a specific team

Provide at least one of player_id or name to identify the player.

Response Content Type

text/html

Example Request

curl -H "X-API-Key: <your_key>" \
  "https://footballperformanceapi.site/report?name=Example%20Player&season=2024%2F2025" \
  -o player_report.html

System

`GET /health`

Check the operational status of the API. This endpoint does not require authentication and can be used for uptime monitoring.

Authentication: None required

Example Request

curl https://footballperformanceapi.site/health

Response

200 OK
Content-Type: application/json

{ ... }

Data Models & Schemas

PredictRequest

Used by POST /score/predict and POST /score/predict-base.

{
  "features": {
    "<feature_name>": <value>,
    ...
  }
}

The features object accepts any key/value pairs. The table below lists all recognised statistical fields with their expected types. For definitions of each metric, see the Feature Reference section.

Recognised Feature Fields

Field	Type	Description
`player_name`	string	Player full name
`position`	string	Player position (e.g. `defender`, `midfielder`, `forward`)
`league`	string	Competition name (e.g. `Premier League`)
`club`	string	Club name
`season`	string	Season string (e.g. `2024/2025`)
`minutes`	integer	Total minutes played
`goals`	integer	Goals scored
`assists`	integer	Assists
`shots`	integer	Total shots
`shots_on_target`	integer	Shots on target
`passes_attempted`	integer	Total passes attempted
`passes_completed`	integer	Passes completed
`tackles`	integer	Total tackles
`tackles_won`	integer	Tackles won
`interceptions`	integer	Interceptions
`clearances`	integer	Clearances
`blocks`	integer	Blocks
`dribbles`	integer	Dribble attempts
`dribbles_successful`	integer	Successful dribbles
`aerials`	integer	Aerial duels contested
`aerials_won`	integer	Aerial duels won
`fouls_committed`	integer	Fouls committed
`fouls_drawn`	integer	Fouls drawn
`yellow_cards`	integer	Yellow cards received
`red_cards`	integer	Red cards received

Full Example Payload

{
  "features": {
    "player_name": "Example Player",
    "position": "defender",
    "league": "Premier League",
    "club": "Example FC",
    "season": "2024/2025",
    "minutes": 1980,
    "goals": 3,
    "assists": 5,
    "shots": 28,
    "shots_on_target": 10,
    "passes_attempted": 1900,
    "passes_completed": 1650,
    "tackles": 68,
    "tackles_won": 45,
    "interceptions": 52,
    "clearances": 140,
    "blocks": 35,
    "dribbles": 42,
    "dribbles_successful": 23,
    "aerials": 90,
    "aerials_won": 56,
    "fouls_committed": 22,
    "fouls_drawn": 18,
    "yellow_cards": 4,
    "red_cards": 0
  }
}

HTTPValidationError

Returned on 422 Unprocessable Entity responses when request validation fails.

{
  "detail": [
    {
      "loc": ["body", "features"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Field	Type	Description
`detail`	array	List of ValidationError objects

ValidationError

Field	Type	Description
`loc`	array of string/integer	Location path of the error (e.g. `["body", "features"]`)
`msg`	string	Human-readable error message
`type`	string	Machine-readable error type

Error Reference

HTTP Status	Meaning	Common Causes
`200 OK`	Success	Request was valid and processed
`401 Unauthorized`	Auth failed	Missing, invalid, or expired API key
`403 Forbidden`	Access denied	Valid key but insufficient plan permissions
`404 Not Found`	Not found	Invalid endpoint path
`422 Unprocessable Entity`	Validation error	Missing required fields, wrong types — see HTTPValidationError
`429 Too Many Requests`	Rate limited	Exceeded request quota for your plan
`500 Internal Server Error`	Server error	Unexpected error on the API side

For persistent errors, check the health endpoint first, then reach out via www.futrixmetrics.com.

Quick Start Examples

Don’t have an API key yet? Request access at www.futrixmetrics.com/services.

1. Query player ratings for a specific league

curl -H "X-API-Key: <your_key>" \
  "https://footballperformanceapi.site/database/ratings?league=Premier%20League&season=2024%2F2025&limit=20"

2. Score a player using the Pro model

curl -X POST \
  -H "X-API-Key: <your_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "features": {
      "player_name": "Example Player",
      "position": "midfielder",
      "league": "La Liga",
      "club": "Example FC",
      "season": "2024/2025",
      "minutes": 2340,
      "goals": 12,
      "assists": 8,
      "passes_attempted": 2100,
      "passes_completed": 1850,
      "tackles": 55,
      "tackles_won": 38,
      "interceptions": 40,
      "clearances": 30,
      "blocks": 20,
      "shots": 60,
      "shots_on_target": 25,
      "dribbles": 80,
      "dribbles_successful": 55,
      "aerials": 50,
      "aerials_won": 28,
      "fouls_committed": 30,
      "fouls_drawn": 45,
      "yellow_cards": 3,
      "red_cards": 0
    }
  }' \
  https://footballperformanceapi.site/score/predict

3. Compare Base vs Pro model scores for the same player

# Pro model
curl -X POST \
  -H "X-API-Key: <your_key>" \
  -H "Content-Type: application/json" \
  -d '{ "features": { ... } }' \
  https://footballperformanceapi.site/score/predict

# Base model
curl -X POST \
  -H "X-API-Key: <your_key>" \
  -H "Content-Type: application/json" \
  -d '{ "features": { ... } }' \
  https://footballperformanceapi.site/score/predict-base

4. Fetch a player scouting report and save to file

curl -H "X-API-Key: <your_key>" \
  "https://footballperformanceapi.site/report?name=Example%20Player&season=2024%2F2025" \
  -o scouting_report.html

5. Find all midfielders in a role cluster

curl -H "X-API-Key: <your_key>" \
  "https://footballperformanceapi.site/database/role-cluster-results?position=midfielder&cluster_group=box-to-box&limit=50"

6. Check API health (no key required)

curl https://footballperformanceapi.site/health

Feature Reference

The table below maps every PredictRequest feature field to its football analytics definition. Use this as a guide when preparing player data before calling POST /score/predict.

For full methodology behind how these features are weighted in the model, visit futrixmetrics.com/project/develop.

Feature	Football Definition
`minutes`	Total minutes the player appeared on the pitch across all matches in the season
`goals`	Total goals scored (excluding own goals)
`assists`	Final passes directly leading to a goal
`shots`	All shot attempts (on target + off target + blocked)
`shots_on_target`	Shots requiring a save or resulting in a goal
`passes_attempted`	All passes attempted, including set pieces
`passes_completed`	Passes that reached a teammate
`tackles`	Attempts to dispossess an opposing player
`tackles_won`	Successful tackles resulting in possession recovery
`interceptions`	Actions preventing an opposition pass from reaching its target
`clearances`	Actions clearing the ball from a defensive situation
`blocks`	Shots or crosses blocked by the player’s body
`dribbles`	Attempts to take on an opposing player with the ball
`dribbles_successful`	Dribble attempts that successfully beat the opponent
`aerials`	Aerial duels contested (headers and shoulder challenges)
`aerials_won`	Aerial duels won
`fouls_committed`	Infringements conceded by the player
`fouls_drawn`	Infringements drawn by the player against opponents
`yellow_cards`	Yellow cards received in the season
`red_cards`	Red cards received in the season

Football Performance API v1.0.0 — Futrix Metrics

Home · About · Services & API Access · Player Rating Project · Development

Football Performance API Documentation — Futrix Metrics

Football Performance API Documentation

Table of Contents

Overview

Base URL

Authentication

Get API Access

Pagination

Endpoints

Database

GET /database/ratings

GET /database/role-cluster-results

GET /database/role-cluster-summary

Score & Prediction

GET /score/

POST /score/predict

POST /score/predict-base

Charts & Visualisation

GET /charts/overview

GET /charts/positions

GET /charts/leagues

GET /charts/models/base

GET /charts/models/pro

GET /charts/features

Reports

GET /report

System

GET /health

Data Models & Schemas

PredictRequest

Recognised Feature Fields

HTTPValidationError

ValidationError

Error Reference

Quick Start Examples

1. Query player ratings for a specific league

2. Score a player using the Pro model

3. Compare Base vs Pro model scores for the same player

4. Fetch a player scouting report and save to file

5. Find all midfielders in a role cluster

6. Check API health (no key required)

Feature Reference

`GET /database/ratings`

`GET /database/role-cluster-results`

`GET /database/role-cluster-summary`

`GET /score/`

`POST /score/predict`

`POST /score/predict-base`

`GET /charts/overview`

`GET /charts/positions`

`GET /charts/leagues`

`GET /charts/models/base`

`GET /charts/models/pro`

`GET /charts/features`

`GET /report`

`GET /health`