> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squadassist.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get sportive impact of a player for a club

> Calculate the on-field impact of a player joining a club — projected league position improvement and estimated revenue contribution over 3 seasons.

The `POST /get_sportive_impact` endpoint calculates the sportive (on-field) impact of a player joining a specific club. It uses SquadAssist's model to simulate how the player would affect the club's squad and expected league position over a 3-year period. The result is expressed both as a monetary value — the revenue contribution the improvement is expected to generate — and as concrete simulation metrics such as the change in expected finishing position and projected playing time. This is the on-field component of the full ROI analysis; no transfer fee or wage inputs are needed here because those belong to the cost side of the calculation.

<Note>
  The analysis always uses the **2025/2026 season** as the starting point. Season is not a request parameter. The `club_id` must be a club in your coverage.
</Note>

## Request

The request body must be a JSON object.

<ParamField body="player_id" type="string" required>
  The SquadAssist player ID. Use `POST /query_player` to look up the ID from a Transfermarkt or Wyscout ID.
</ParamField>

<ParamField body="club_id" type="string" required>
  The SquadAssist club ID for the club the player would be joining. The model compares the player against the club's existing squad to determine playing time and positional improvement. Use `POST /query_club` to look up the ID.
</ParamField>

<ParamField body="currency_code" type="string">
  An [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code (e.g. `EUR`, `GBP`, `USD`). The on-field monetary value will be returned in this currency alongside the EUR value. Defaults to `EUR`.
</ParamField>

## Response

<ResponseField name="currency" type="string">
  The ISO 4217 currency code for the `on_field_value` output. Matches your `currency_code` input, or `EUR` if none was provided.
</ResponseField>

<ResponseField name="on_field_value" type="integer">
  The estimated monetary value of the player's on-field contribution to the club over the 3-year simulation, in the requested currency. This reflects the additional revenue the club is expected to generate from the improvement in league position.
</ResponseField>

<ResponseField name="on_field_value_in_eur" type="integer">
  The estimated on-field value contribution, in EUR.
</ResponseField>

<ResponseField name="simulation" type="object">
  The league position simulation results showing how the player changes the club's expected finishing position.

  <Expandable title="simulation fields">
    <ResponseField name="increase_in_expected_position" type="number">
      The improvement in expected league finishing position when the player joins (original minus new expected position, floored at 0). A higher number means a larger positive impact.
    </ResponseField>

    <ResponseField name="new_expected_position" type="number">
      The club's expected league finishing position with the player in the squad. Lower is better (1st place = 1).
    </ResponseField>

    <ResponseField name="original_expected_position" type="number">
      The club's expected league finishing position without the player. Lower is better.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="playing_time_percentage" type="number">
  The projected fraction of available matches the player is expected to participate in at the signing club (0.0–0.9). For example, `0.72` means the player is expected to play in approximately 72% of matches.
</ResponseField>

## Example

<CodeGroup>
  ```bash PowerShell theme={null}
  $headers = @{
      "x-api-key"    = "your API key" # Change
      "Content-Type" = "application/json"
  }

  $body = @{
      "player_id"               = "P01K0WPQJPWZCNCYH1KXHTJ9R31" #Change ID to desired player
      "club_id"                 = "C01JJBVJAPKG8CM7ZA5JF5G84R8" #Change ID to desired buying club
      "currency_code"           = "EUR"
  }

  Invoke-RestMethod -Uri "https://api.squadassist.ai/v1/get_sportive_impact" `
                    -Method Post `
                    -Headers $headers `
                    -Body ($body | ConvertTo-Json)
  ```

  ```python Python theme={null}
  import requests

  # 1. Define the endpoint
  url = "https://api.squadassist.ai/v1/get_sportive_impact"

  # 2. Set up your headers
  headers = {
      "x-api-key": "your_API_key",  # Replace with your actual key
      "Content-Type": "application/json"
  }

  # 3. Define the data 
  payload = {
      "player_id": "P01K0WPQJPWZCNCYH1KXHTJ9R31",
      "club_id": "C01JJBVJAPKG8CM7ZA5JF5G84R8",
      "currency_code": "EUR"
  }

  # 4. Make the POST request
  response = requests.post(url, headers=headers, json=payload)

  # 5. Output the result
  if response.status_code == 200:
      data = response.json()
      print("Success!")
      print(data)
  else:
      print(f"Error {response.status_code}: {response.text}")
  ```
</CodeGroup>

<CodeGroup>
  ```json Response theme={null}
  {
    "currency": "EUR",
    "on_field_value": 6800000,
    "on_field_value_in_eur": 6800000,
    "simulation": {
      "increase_in_expected_position": 2,
      "new_expected_position": 4.1,
      "original_expected_position": 6.1
    },
    "playing_time_percentage": 0.72
  }
  ```
</CodeGroup>

## Errors

| Status | Body                                                | Cause                                               |
| ------ | --------------------------------------------------- | --------------------------------------------------- |
| `400`  | `{"error": "player_id is required"}`                | `player_id` was not included in the request body    |
| `400`  | `{"error": "club_id is required"}`                  | `club_id` was not included in the request body      |
| `400`  | `{"error": "Invalid player_id"}`                    | The `player_id` format is not valid                 |
| `400`  | `{"error": "Invalid club_id"}`                      | The `club_id` format is not valid                   |
| `400`  | `{"error": "currency_code must be a string"}`       | `currency_code` was provided but is not a string    |
| `400`  | `{"error": "<message>"}`                            | The `currency_code` is not a valid ISO 4217 code    |
| `403`  | `{"error": "Player is not in the allowed leagues"}` | The player is not in the Belgian Jupiler Pro League |
| `403`  | `{"error": "Requested club is not allowed"}`        | The `club_id` is not available on your plan         |
| `404`  | `{"error": "Club not found"}`                       | No club was found for the provided `club_id`        |