API Documentation

Prediction Endpoint

This endpoint is used to get an xG prediction for a single shot. It requires a POST request with a JSON body containing the shot's features.

Endpoint

Request Body

{
    "x": 89.25,
    "y": 34.0,
    "situation": "OpenPlay",
    "shot_type": "RightFoot",
    "normalisation": {
        "is_normalised": false,
        "max_pitch_width": 68,
        "max_pitch_length": 105
    }
}

Parameters

• x (float, required): The x-coordinate of the shot. Can be a raw coordinate (e.g., in metres) or a normalised value between 0 and 1. See the normalisation parameter for details.
• y (float, required): The y-coordinate of the shot. Can be a raw coordinate (e.g., in metres) or a normalised value between 0 and 1. See the normalisation parameter for details.
• situation (string, optional): The game situation. If provided, a more specific model that accounts for the situation is used. Valid values are: OpenPlay, SetPiece, DirectFreekick, FromCorner, Penalty.
• shot_type (string, optional): The type of shot. If provided, a more specific model that accounts for the shot type is used. Valid values are: Head, RightFoot, LeftFoot, OtherBodyPart.
• normalisation (object, required): An object for handling coordinate normalisation.
  • is_normalised (boolean, required): Must be set to true if the provided x and y are already normalised (between 0 and 1). Set to false if they are raw coordinates that require normalisation by the API.
  • max_pitch_width (float, conditional): The pitch width (e.g., 68) to use for normalisation. Required if is_normalised is false.
  • max_pitch_length (float, conditional): The pitch length (e.g., 105) to use for normalisation. Required if is_normalised is false.

  Example for raw coordinates: {"is_normalised": false, "max_pitch_width": 68, "max_pitch_length": 105}

  Example for normalised coordinates: {"is_normalised": true}

Successful Response (200 OK)

A successful request returns a JSON object with the prediction and metadata about the model's inference process.

{
    "xG": 0.23,
    "inputs": {
        "x": 0.92,
        "y": 0.57,
        "situation": "OpenPlay",
        "shot_type": "RightFoot",
        "normalisation": {
            "is_normalised": false,
            "max_pitch_width": 68,
            "max_pitch_length": 105
        }
    },
    "chosen_model": "advanced_model",
    "chosen_model_features": [
        "X",
        "Y",
        "distance_to_goal",
        "angle_to_goal",
        "situation_OpenPlay",
        "shotType_RightFoot",
        "interaction_OpenPlay_RightFoot",
        "..."
    ]
}

Response Body

• xG (float): The calculated Expected Goals (xG) value for the shot, rounded to two decimal places.
• inputs (object): An object containing the exact inputs that were used by the model for prediction.
  • Note: The x and y values in this object are the normalised coordinates (0-1 range) that were fed into the model. If you provided raw coordinates, these values will show the result of the normalisation performed by the API.
• chosen_model (string): The name of the machine learning model selected by the API based on the provided inputs. Different models are used depending on whether situation and/or shot_type were provided.
• chosen_model_features (array of strings): A list of the specific feature names that the chosen model used to make the prediction. This includes the base coordinates and any derived or one-hot encoded features.

Error Responses

• 400 Bad Request: Returned for invalid input. The response body will contain an error key with a descriptive message, such as:
  • "Missing x or y coordinate"
  • "Invalid situation - ..."
  • "Invalid shot type - ..."
  • "x and y must be numeric values."
  • "Normalisation dictionary must contain 'is_normalised' key."
  • "In order to carry out normalisation... a max pitch width and a max pitch length need to be provided."
  • "The maximum width and length of the pitch cannot be a negative value."
  • "Coordinates have been incorrectly claimed as normalised..."
• 500 Internal Server Error: Returned for unexpected server errors. The response will contain a generic error message.

Heatmap Grid Endpoint

This endpoint provides a pre-calculated grid of xG values for generating a heatmap. It's a GET request and takes query parameters to filter the data.

Endpoint

Query Parameters

Filter the heatmap grid by providing the following optional query parameters. If no parameters are provided, a default grid is returned.

• situation (string, optional): Filters the grid for a specific game situation. If omitted, the grid will not be filtered by situation. Valid values are: OpenPlay, SetPiece, DirectFreekick, FromCorner. Note: 'Penalty' is not supported for grid prediction.
• shot_type (string, optional): Filters the grid for a specific shot type. If omitted, the grid will not be filtered by shot type. Valid values are: Head, RightFoot, LeftFoot, OtherBodyPart.
• max_length (float, optional): The maximum length of the pitch (e.g., 105). If provided along with max_width, the x_coords in the response will be scaled to this dimension. Otherwise, coordinates are returned in their normalised (0-1) form.
• max_width (float, optional): The maximum width of the pitch (e.g., 68). If provided along with max_length, the y_coords in the response will be scaled to this dimension. Otherwise, coordinates are returned in their normalised (0-1) form.

Example Usage

Successful Response (200 OK)

Returns a JSON object containing the grid definition and the corresponding heatmap data.

{
    "grid_definition": {
        "x_coords": [0.5, 0.52, ..., 1.0],
        "y_coords": [0.0, 0.02, ..., 1.0]
    },
    "heatmap": [
        [0.01, 0.01, ..., 0.02],
        [0.01, 0.01, ..., 0.02],
        ...
    ]
}

Response Body

• grid_definition (object): Contains the coordinate arrays for the heatmap grid.
  • x_coords (array of floats): The list of x-coordinates for the grid's columns. These will be scaled if max_length was provided in the request.
  • y_coords (array of floats): The list of y-coordinates for the grid's rows. These will be scaled if max_width was provided in the request.
• heatmap (2D array of floats): A 2D array (matrix) of xG values. Each value corresponds to the intersection of an x and y coordinate from the grid_definition. The structure is heatmap[y_index][x_index].

Error Responses

• 400 Bad Request: Returned for invalid query parameters. The response body will contain an error key with a descriptive message, such as:
  • "The 'Penalty' situation is not available for grid prediction."
  • "Invalid situation. ..."
  • "Invalid shot type - ..."
  • "max_length and max_width must be positive numbers."
• 404 Not Found: Returned if no heatmap data exists for the specified situation and shot_type combination.
• 500 Internal Server Error: Returned if the heatmap data file cannot be found on the server or for other unexpected errors.