Add getSeasonSimulations() #124

Type of Addition

Entirely new endpoint

Endpoint Name/Path

/v5/customerapi/iterations/{iterationId}/predictions/season-simulations

Field Details

For every simulation date, a season simulation shows the actual table, the expected final points and goals and the probability of every finishing position of each squad (20,000 simulations of the rest of the season, based on the squad model coefficients).

Response structure (data):

• iterationId: integer
• predictions: array, one entry per simulation date, oldest first
  • date: string (YYYY-MM-DD)
  • stageName: string, null for a plain league (e.g. Apertura/Clausura)
  • squadPredictions: array, ordered by group and squad ID
    • squadId: integer
    • groupName: string, null for a plain league (e.g. groups/conferences)
    • matches, points, goalsFor, goalsAgainst: integer (actual table)
    • pointsProjected, goalsForProjected, goalsAgainstProjected: float
    • rankProbabilities: array of floats, one per finishing position within the squad's group

impectPy already provides getSeasonSimulations() for this endpoint.

New Endpoint Details (if applicable)

• HTTP Method: GET
• Parameters:
  • iterationId (required): integer
  • date (optional query parameter): string YYYY-MM-DD, returns only the latest simulation on or before that date
• Proposed R function: getSeasonSimulations(iteration, token, date = NULL, host)

API Documentation Reference

API changelog 21.10.2026 - Season Simulations added

Example API Response

{
  "iterationId": 1813,
  "predictions": [
    {
      "date": "2026-05-14",
      "stageName": "Intermedio",
      "squadPredictions": [
        {
          "squadId": 488,
          "groupName": "Serie A",
          "matches": 0,
          "points": 0,
          "goalsFor": 0,
          "goalsAgainst": 0,
          "pointsProjected": 13.502,
          "goalsForProjected": 11.65,
          "goalsAgainstProjected": 5.371,
          "rankProbabilities": [0.455, 0.223, 0.132, 0.083, 0.05, 0.033, 0.016, 0.007]
        }
      ]
    }
  ]
}

Proposed Implementation (Optional)

Acceptance criteria

• New exported function getSeasonSimulations(iteration, token, date = NULL, host).
• One row per simulation date and squad; rankProbabilities expanded into rank1Probability, rank2Probability, ... (NA where a group has fewer ranks).
• Merge competition info and squad name/provider IDs.
• Output columns and order are identical to impectPy.getSeasonSimulations().
• Add roxygen docs, an example, and a NEWS entry.

Additional Context

Parity with impectPy.