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

Vesna — Sun, 21 Jun 2026 13:27:25 +0000

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:

discover the relevant World Cup league data dynamically
combine tournament history with recent national-team form
train models from cached data
generate fresh outputs without manual cleanup
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

Under the hood, that flow:

discovers the World Cup league id
downloads seasons and historical World Cup matches
pulls recent national-team matches
trains the models
predicts future World Cup fixtures
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/

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]

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

Run the full workflow:

python -m wc2026_predictor run-all

Or use the PowerShell wrapper:

./scripts/run_pipeline.ps1

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"

DEV Community: Vesna