Skip to main content

LineupAPI: How it works

How it works

LineupAPI provides prediction data for upcoming football (soccer) fixtures — ready for apps, tools, and spreadsheets.

It’s built for questions like:

  • Who is likely to start?
  • Who might come off the bench?
  • When might a starter be subbed off?
  • What are the chances for minutes, goals, assists, cards, and other match events?
What LineupAPI is used for

Typical use cases:

  • Spreadsheets (CSV output for Excel / Google Sheets)
  • Dashboards (probabilities for minutes and player involvement)
  • Widgets & content (probable starting lineup, formation, bench, match previews)
  • Backtesting (historical snapshots via /history/*)

Why it’s useful

Football is messy: lineups shift, players get injured, and team performance far in advance is uncertain.

So LineupAPI focuses on:

  • Lineup probabilities (starter, benchAndPlay, notPlay) to model player involvement
  • Prediction groups (minutes, goals, assists, cards, etc.) to model player-level outcomes
  • CSV outputs designed for fast and easy integration (no programming required)

Predictions are grouped

Predictions are organized into groups, such as:

  • lineups
  • minutes
  • goals
  • assists
  • cards
  • corners_taken
  • fouls_won
  • fouls_conceded

Tips

Only request the groups you need to keep responses and cost small.

The core flow

LineupAPI works in two steps:

  1. Get fixtures
    Use /fixtures to discover upcoming matches in the forecast window and pick a fixtureId.

  2. Get predictions of a fixture
    Use /predictions/{fixtureId} with groups=... to download prediction data as CSV.

Forecast window and updates

LineupAPI predicts fixtures up to 17 days in advance.

Predictions for a fixture are refreshed on a 24-hour interval before kickoff, so you can reliably know when to request an updated prediction. Fixtures themselves can be discovered more frequently via /fixtures.

Predictions metadata

Every prediction result is part of a snapshot.

  • The main prediction endpoints return CSV
  • /predictions/metadata/{fixtureId} returns JSON with all created snapshots and their creation timings and model/version details

History Predictions

History endpoints exist so you can retrieve “what the API said back then”. The coverage starts on 2023-07-25 (older timestamps are not available). Advanced developers can find these extra headers returned on every successful request:

  • x-timestamp-requested: The ISO 8601 timestamp you provided via the date query parameter.
  • x-timestamp-current: The closest snapshot timestamp found that is at or before x-timestamp-requested.
  • x-timestamp-previous: The closest available snapshot timestamp before x-timestamp-current (if available).
  • x-timestamp-next: The closest available snapshot timestamp after x-timestamp-current (if available).

Tip

These headers make it easy to navigate between snapshots (e.g., move one backward using x-timestamp-previous, or forward using x-timestamp-next) without guessing valid timestamps (date parameters).