DEV Community

Vesna
Vesna

Posted on

I Built a World Cup 2026 Prediction Pipeline with Sportmicro, Python, and GitHub Actions

#python #machinelearning #opensource #api

I wanted a football prediction project that felt closer to a real data product than a one-off notebook.

So I built a pipeline that:

  • pulls World Cup and national-team data from Sportmicro
  • engineers match and team-form features
  • trains a hybrid prediction model
  • generates upcoming fixture predictions and provisional title odds
  • exports machine-readable outputs
  • can refresh itself on a schedule through GitHub Actions

The repo is here:

world-cup-2026-prediction-sportmicro-api

What problem I was trying to solve

A lot of sports prediction demos stop at one model and one CSV. That is fine for experimentation, but it breaks down quickly if you want something you can rerun, automate, or publish.

For this project, I wanted a workflow that could:

  1. discover the relevant World Cup league data dynamically
  2. combine tournament history with recent national-team form
  3. train models from cached data
  4. generate fresh outputs without manual cleanup
  5. fit naturally into CI/CD

The result is a small but production-style sports analytics pipeline.

The stack

  • Python for data fetching, feature engineering, training, and reporting
  • scikit-learn for classification and score expectation models
  • pandas and numpy for the data layer
  • Node.js only where it adds value: generating Sportmicro endpoint paths through the official @sportmicro/endpoint package
  • GitHub Actions for scheduled refreshes

That Python + Node split is deliberate. The modeling and orchestration live in Python, while the API query construction stays aligned with Sportmicro's official endpoint builder.

Why the Sportmicro integration is interesting

Instead of hardcoding raw query strings, the repo sends a JSON request spec from Python to a Node helper script, and the helper builds the final endpoint path using @sportmicro/endpoint.

That means filters like eq, gte, in(...), pagination, and ordering are all constructed in a consistent way.

This is the part I like most architecturally: Python stays clean, and the final URL generation still uses the official tooling intended for the API.

Example shape of the workflow:

python -m wc2026_predictor run-all
Enter fullscreen mode Exit fullscreen mode

Under the hood, that flow:

  1. discovers the World Cup league id
  2. downloads seasons and historical World Cup matches
  3. pulls recent national-team matches
  4. trains the models
  5. predicts future World Cup fixtures
  6. writes reports and CSV/JSON outputs

How the model works

This is not a single-model predictor.

The repo uses a layered approach:

  • Elo-style team strength updates
  • rolling form features from recent matches
  • a RandomForestClassifier for match outcome classification
  • two PoissonRegressor models for expected home and away goals
  • a hybrid ensemble that blends ML probabilities, Elo expectation, and Poisson-derived outcome probabilities

I used this design because football is noisy. A pure classifier can miss score dynamics, and a pure Poisson model can miss richer recent-form patterns. Combining them gives a more balanced prediction layer.

What the pipeline outputs

Each run produces artifacts that are useful both for people and for downstream systems:

  • predictions/latest_match_predictions.csv
  • predictions/latest_match_predictions.json
  • predictions/title_odds.csv
  • predictions/title_odds.json
  • predictions/report.md

The match predictions include:

  • predicted result
  • home/draw/away probabilities
  • expected goals
  • most likely scoreline

The title odds are intentionally labeled as provisional when the full tournament structure is not yet available from the API.

A small detail that matters: automation

I also wired the repo to run through GitHub Actions on a schedule and by manual dispatch.

The workflow:

  • installs Python and Node
  • installs dependencies
  • runs the full prediction pipeline
  • commits refreshed outputs back into the repository

That turns the project from "interesting code" into something that can act like a living forecast feed.

Project structure 

world-cup-2026-prediction-sportmicro-api/
├─ .github/workflows/automation.yml
├─ scripts/build_endpoint.mjs
├─ scripts/run_pipeline.ps1
├─ src/wc2026_predictor/
│  ├─ cli.py
│  ├─ endpoint_builder.py
│  ├─ features.py
│  ├─ modeling.py
│  ├─ pipeline.py
│  ├─ reporting.py
│  └─ sportmicro.py
├─ data/
├─ artifacts/
└─ predictions/
Enter fullscreen mode Exit fullscreen mode

I tried to keep the boundaries clean:

  • sportmicro.py handles API access and normalization
  • features.py builds the training and fixture frames
  • modeling.py owns training and prediction logic
  • pipeline.py orchestrates the end-to-end flow
  • reporting.py turns outputs into a readable Markdown report

Running it locally

Setup is straightforward:

npm install
python -m pip install --upgrade pip
python -m pip install .[dev]
Enter fullscreen mode Exit fullscreen mode

Then create .env from .env.example and set your API key:

SPORTMICRO_API_KEY=your_sportmicro_api_key_here
SPORTMICRO_BASE_URL=https://football.sportmicro.com
WC2026_PREDICTION_START_DATE=2026-01-01
WC2026_RECENT_MATCH_START_DATE=2021-01-01
Enter fullscreen mode Exit fullscreen mode

Run the full workflow:

python -m wc2026_predictor run-all
Enter fullscreen mode Exit fullscreen mode

Or use the PowerShell wrapper:

./scripts/run_pipeline.ps1
Enter fullscreen mode Exit fullscreen mode

What I would improve next

There is still plenty of room to push this further:

  • add probability calibration analysis
  • bring in more match-statistics features
  • simulate bracket progression once full 2026 structure is available
  • publish a small dashboard on top of the generated outputs

Those are the kinds of upgrades that would move the project from "useful forecasting repo" to "full sports analytics product."

Final thought

The part I care about most in projects like this is not just prediction accuracy. It is whether the system is structured well enough to rerun, inspect, automate, and extend.

That was the goal here: build a World Cup 2026 prediction repo that is practical, composable, and easy to evolve.

If you are building in sports analytics, APIs, or ML pipelines, I think this pattern is more useful than another isolated notebook.

If you want, I can also turn this into:

  • a shorter dev.to version with a more punchy hook
  • a more SEO-focused version
  • a version written in a more personal "build in public"

Top comments (3)

Collapse
 
nazar_boyko profile image
Nazar Boyko •

The part that stuck with me is blending the RandomForest with the Poisson goal models instead of picking one. Outcome classifiers tend to flatten the scoreline detail, so leaning on Poisson for expected goals fills a real gap there. The thing I'd be curious about is how you weight the three signals when they disagree, since a close match is exactly where the Elo expectation and the classifier can pull in opposite directions. Labeling the title odds as provisional until the bracket is known is the honest call too.

Collapse
 
mihailove123 profile image
Miheve •

Can you send us the github link?

Some comments may only be visible to logged-in visitors. Sign in to view all comments.