Getting Started

Prerequisites

• RapidAPI account and API key
• Basic understanding of REST APIs
• Familiarity with JSON data format

Authentication

All requests require RapidAPI authentication headers. You can get your API key and test endpoints on the RapidAPI playground.

X-RapidAPI-Key: YOUR_API_KEY
X-RapidAPI-Host: athlemetrics-player-score-predictor.p.rapidapi.com

Key Features

• Player performance predictions using ML models
• Role clustering and player similarity analysis
• Customizable feature inputs with per-90-minute normalization
• Multiple model types (Gradient Boosting, Ridge Regression)
• Comprehensive player search functionality

1. Prediction Endpoints

Example Request:

curl -X GET "https://athlemetrics-player-score-predictor.p.rapidapi.com/base-score/kits" \
  -H "X-RapidAPI-Key: YOUR_API_KEY" \
  -H "X-RapidAPI-Host: athlemetrics-player-score-predictor.p.rapidapi.com"

Example Response:

{
  "kits": [
    {
      "name": "attacker_core",
      "description": "Core features for attacking players",
      "fields": ["goals_per90", "assists_per90", "shots_per90", "xG_per90"]
    },
    {
      "name": "midfielder_core",
      "description": "Core features for midfield players",
      "fields": ["passes_per90", "tackles_per90", "interceptions_per90"]
    }
  ]
}

Get Slider Parameters

curl -X GET "https://athlemetrics-player-score-predictor.p.rapidapi.com/base-score/slider-params?kit_name=attacker_core&alias=goals_per90" \
  -H "X-RapidAPI-Key: YOUR_API_KEY" \
  -H "X-RapidAPI-Host: athlemetrics-player-score-predictor.p.rapidapi.com"

Predict Player Score

Request Body:

{
  "kit_name": "attacker_core",
  "payload": {
    "goals_per90": 0.65,
    "assists_per90": 0.35,
    "shots_per90": 3.2,
    "xG_per90": 0.55,
    "key_passes_per90": 1.8
  },
  "model_type": "gb",
  "name": "Custom Player",
  "team": "Example FC",
  "league": "Premier League",
  "season": 2024,
  "show_features": true,
  "score_scale": "0-10",
  "module_filter": "All"
}

Example Response:

{
  "player_name": "Test Player",
  "team": "Example FC",
  "league": "Premier League",
  "overall_score": 8.2,
  "score_scale": "0-10",
  "model_type": "gb",
  "features_breakdown": {
    "attacking": {
      "score": 8.5,
      "features": {
        "goals_per90": 0.65,
        "assists_per90": 0.35
      }
    },
    "shooting": {
      "score": 7.8,
      "features": {
        "shots_per90": 3.2
      }
    }
  }
}

List Available Models

2. Player Role Clustering

Search Players

curl -X GET "https://athlemetrics-player-score-predictor.p.rapidapi.com/role-cluster/search?query=Salah&limit=10" \
  -H "X-RapidAPI-Key: YOUR_API_KEY" \
  -H "X-RapidAPI-Host: athlemetrics-player-score-predictor.p.rapidapi.com"

Example Response:

{
  "results": [
    {
      "record_id": 12345,
      "player_name": "Mohamed Salah",
      "squad": "Liverpool",
      "position": "RW",
      "season": 2024,
      "cluster_id": 3,
      "role_description": "Advanced Forward"
    }
  ],
  "total": 1,
  "limit": 10
}

Get Role Legend

{
  "legends": {
    "0": {
      "role": "Defensive Midfielder",
      "sample_count": 2450,
      "characteristics": ["High tackles", "Positional discipline"]
    },
    "1": {
      "role": "Box-to-Box Midfielder",
      "sample_count": 3200,
      "characteristics": ["Balanced stats", "High stamina"]
    }
  }
}

Predict Role by Record ID

Predict Role with Custom Features

{
  "label_source": null,
  "feature_payload": {
    "goals_per90": 0.7,
    "assists_per90": 0.4,
    "shots_per90": 3.5,
    "dribbles_per90": 2.8,
    "passes_per90": 45.0,
    "tackles_per90": 0.8
  }
}

3. Advanced Usage Examples

Example 1: Complete Player Analysis Workflow

This Python example demonstrates how to search for a player, get their role prediction, and calculate a custom performance score. For more examples and starter code, check out our GitHub repository.

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://athlemetrics-player-score-predictor.p.rapidapi.com"
HEADERS = {
    "X-RapidAPI-Key": API_KEY,
    "X-RapidAPI-Host": "athlemetrics-player-score-predictor.p.rapidapi.com"
}

# Step 1: Search for a player
search_response = requests.get(
    f"{BASE_URL}/role-cluster/search",
    headers=HEADERS,
    params={"query": "Haaland", "limit": 5}
)
players = search_response.json()

# Step 2: Get role prediction
if players["results"]:
    record_id = players["results"][0]["record_id"]
    role_response = requests.get(
        f"{BASE_URL}/role-cluster/predict/record/{record_id}",
        headers=HEADERS
    )
    role_data = role_response.json()
    print(f"Player Role: {role_data['role_description']}")

# Step 3: Predict custom score
payload = {
    "kit_name": "attacker_core",
    "payload": {
        "goals_per90": 0.95,
        "assists_per90": 0.25,
        "shots_per90": 4.2
    },
    "model_type": "gb",
    "name": "Erling Haaland",
    "score_scale": "0-10"
}

score_response = requests.post(
    f"{BASE_URL}/base-score/predict",
    headers=HEADERS,
    json=payload
)
score_data = score_response.json()
print(f"Predicted Score: {score_data['overall_score']}/10")

Example 2: Batch Player Comparison

const axios = require('axios');

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://athlemetrics-player-score-predictor.p.rapidapi.com';
const headers = {
  'X-RapidAPI-Key': API_KEY,
  'X-RapidAPI-Host': 'athlemetrics-player-score-predictor.p.rapidapi.com'
};

async function compareForwards(playerNames) {
  const results = [];
  
  for (const name of playerNames) {
    const searchRes = await axios.get(
      `${BASE_URL}/role-cluster/search`,
      { headers, params: { query: name, limit: 1 } }
    );
    
    if (searchRes.data.results.length > 0) {
      const player = searchRes.data.results[0];
      
      const roleRes = await axios.get(
        `${BASE_URL}/role-cluster/predict/record/${player.record_id}`,
        { headers }
      );
      
      results.push({
        name: player.player_name,
        team: player.squad,
        role: roleRes.data.role_description,
        confidence: roleRes.data.confidence
      });
    }
  }
  
  return results;
}

// Usage
compareForwards(['Haaland', 'Mbappe', 'Kane'])
  .then(data => console.log(data));

Example 3: Dynamic Feature Input UI

# Get slider parameters for building a form
def get_kit_parameters(kit_name):
    params_data = {}
    
    # Get available fields for kit
    kits_response = requests.get(
        f"{BASE_URL}/base-score/kits",
        headers=HEADERS
    )
    
    kit_info = next(
        (k for k in kits_response.json()["kits"] if k["name"] == kit_name),
        None
    )
    
    if kit_info:
        for field in kit_info["fields"]:
            slider_response = requests.get(
                f"{BASE_URL}/base-score/slider-params",
                headers=HEADERS,
                params={"kit_name": kit_name, "alias": field}
            )
            params_data[field] = slider_response.json()
    
    return params_data

# Example usage
attacker_params = get_kit_parameters("attacker_core")
for field, params in attacker_params.items():
    print(f"{field}: min={params['min']}, max={params['max']}, default={params['default']}")

4. Best Practices

Rate Limiting

• Monitor your API usage to stay within RapidAPI limits
• Implement exponential backoff for retry logic
• Cache responses when appropriate (especially for static data like kits and legends)

Error Handling

Always implement comprehensive error handling:

try:
    response = requests.post(
        f"{BASE_URL}/base-score/predict",
        headers=HEADERS,
        json=payload,
        timeout=10
    )
    response.raise_for_status()
    data = response.json()
except requests.exceptions.Timeout:
    print("Request timed out")
except requests.exceptions.HTTPError as e:
    print(f"HTTP error occurred: {e}")
except requests.exceptions.RequestException as e:
    print(f"Error occurred: {e}")

Data Validation

Validate inputs before sending requests:

def validate_per90_stat(value, stat_name):
    if value < 0:
        raise ValueError(f"{stat_name} cannot be negative")
    if value > 10:  # Sanity check
        print(f"Warning: {stat_name}={value} seems unusually high")
    return value

Optimize Payload Size

payload = {
    "kit_name": "attacker_core",
    "payload": {"goals_per90": 0.65},
    "model_type": "gb"
}

payload = {
    "kit_name": "attacker_core",
    "payload": {"goals_per90": 0.65},
    "model_type": "gb",
    "show_features": True,  # Only if needed
    "module_filter": "All"  # Use default when possible
}

5. Common Use Cases

6. Troubleshooting

Common Issues

Additional Resources