openmatchkit 0.2.2

Unofficial open-source football match data toolkit using public sources.

openmatchkit

Unofficial open-source football match data toolkit for fixtures, results, best-effort live score adapters, standings, exports, and simple prediction models.

This project is unofficial and not affiliated with FIFA, any league, club, broadcaster, federation, or data provider. It does not provide official FIFA data.

Why openmatchkit?

openmatchkit gives Python developers a clean, source-attributed way to work with public football match facts without paid API keys. It starts with open/public datasets, keeps scraping optional and conservative, and returns structured JSON-ready models.

Install

pip install openmatchkit

From GitHub:

pip install git+https://github.com/patilprashan246/openmatchkit.git@v0.2.2

For local development:

python -m venv .venv
.venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
pytest

Quick Start

from openmatchkit import MatchClient

client = MatchClient()
next_match = client.next_match(competition="worldcup", season="2026")

print(next_match.model_dump(mode="json"))

openmatch next-match --competition worldcup --season 2026

Python API

from openmatchkit import MatchClient

client = MatchClient()

fixtures = client.fixtures(competition="worldcup", season="2026")
results = client.results(competition="worldcup", season="2026")
live = client.live_scores()
next_match = client.next_match(competition="worldcup", season="2026")
prediction = client.predict(home="Mexico", away="South Africa", history=results)

client.export_json(fixtures, "fixtures.json")
client.export_csv(fixtures, "fixtures.csv")

League datasets from OpenFootball can be fetched with codes such as:

matches = client.fixtures(competition="en.1", season="2015-16")

CLI

openmatch fixtures --competition worldcup --season 2026
openmatch results --competition en.1 --season 2015-16 --format csv --output results.csv
openmatch next-match --competition worldcup --season 2026
openmatch standings --competition worldcup --season 2026
openmatch predict --home Mexico --away "South Africa" --competition worldcup --season 2026

Detailed JSON feeds can expose richer scoreboards and player history:

openmatch scoreboards --data-file tests/fixtures/sample_detailed_source.json
openmatch scoreboard --match-id detail-1 --data-file tests/fixtures/sample_detailed_source.json
openmatch live-scoreboards --data-file tests/fixtures/sample_detailed_source.json
openmatch player-history --player "Alex Demo" --data-file tests/fixtures/sample_detailed_source.json

from openmatchkit import MatchClient
from openmatchkit.sources.json_file import JsonFileSource

client = MatchClient(sources=[JsonFileSource("tests/fixtures/sample_detailed_source.json")])
scoreboard = client.scoreboard(match_id="detail-1")
history = client.player_history("Alex Demo")
print(scoreboard.model_dump(mode="json"))
print(history.model_dump(mode="json"))

Example Output

{
  "competition": "World Cup 2026",
  "home": {"name": "Canada"},
  "away": {"name": "Bosnia & Herzegovina"},
  "status": "scheduled",
  "source": "openfootball"
}

Features

• Unified match, scoreboard, player history, standings, and prediction models
• OpenFootball JSON adapter
• Football-Data.co.uk CSV adapter
• Local detailed JSON adapter for authorized/public detailed feeds
• Generic optional public HTML adapter
• Safe HTTP client with robots.txt checks, caching, user agent, and per-origin delay
• Fixtures, results, next match, live score adapter interface, team info, standings
• Detailed scoreboards: clock, events, lineups, team stats, and player match stats when provided
• Player histories aggregated from player-level source data
• Simple Poisson prediction baseline and small Elo rating helper
• JSON and CSV export helpers
• Offline tests using local fixtures

Current Status

• Stable enough for demos, research, education, and early open-source feedback
• Not official live FIFA data
• True live/player-level data requires a lawful source adapter that provides those facts
• Public roadmap: ROADMAP.md
• Release notes: CHANGELOG.md

Source and legal policy

The package code is MIT licensed. Third-party data sources have their own licenses and terms. Optional scraping adapters must respect Terms of Service, robots.txt, caching, and rate limits. Player-level data should only come from public or authorized sources and should contain public sporting facts, not private or sensitive information.

See DATA_SOURCES.md, PRIVACY.md, and CONTRIBUTING.md.

Development

python -m pip install -e ".[dev]"
ruff check .
ruff format .
pytest
python -m build

The prediction output is an educational baseline only. It is not betting, financial, or professional advice.