pip install openmatchkit

Released: Jun 12, 2026

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

Navigation

Verified details

Unverified details

  • License: MIT License (MIT License)
  • Author: Prashant Patil
  • Tags cli , fixtures , football , open-data , prediction , scores , soccer , world-cup
  • Requires: Python >=3.10
  • Provides-Extra: dev
  • Development Status 3 - Alpha
  • 3 - Alpha
  • Intended Audience Developers Education Science/Research
  • Developers
  • Education
  • Science/Research
  • License OSI Approved :: MIT License
  • OSI Approved :: MIT License
  • Operating System OS Independent
  • OS Independent
  • Programming Language Python :: 3 Python :: 3.10 Python :: 3.11 Python :: 3.12 Python :: 3.13
  • Python :: 3
  • Python :: 3.10
  • Python :: 3.11
  • Python :: 3.12
  • Python :: 3.13
  • Topic Software Development :: Libraries :: Python Modules
  • Software Development :: Libraries :: Python Modules

Project description

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

For local development:

Quick Start

Python API

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

Functionality Reference

All public models are Pydantic models. Use .model_dump(mode="json") when you want JSON-ready dictionaries, or use the CLI commands when you want JSON printed directly.

Source Metadata

Returns source capability and local health metadata:

Fixtures, Results, Search, Upcoming, Recent

Each item is a Match:

Scoreboards and Match Summaries

Scoreboard can include match clock, lineups, events, team stats, and player stats when the configured source provides them:

Teams, Standings, Form, Head-to-Head

TeamForm returns recent results from the team perspective:

HeadToHeadSummary returns aggregate history plus latest matches:

Player History

Player history depends on a source that legally provides player-level public match facts. The default OpenFootball adapter does not include player stats, but JsonFileSource supports detailed authorized feeds:

Prediction

Returns an educational baseline only:

Export

JSON export keeps full nested model data. CSV export flattens match-level fields for spreadsheet tools.

CLI

Detailed JSON feeds can expose richer scoreboards and player history:

Example Output

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, search, upcoming/recent matches, next match, live score adapter interface
  • Source capabilities and health metadata
  • Team info, grouped standings, team form, and head-to-head summaries
  • 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

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

Project details

Verified details

Unverified details

  • License: MIT License (MIT License)
  • Author: Prashant Patil
  • Tags cli , fixtures , football , open-data , prediction , scores , soccer , world-cup
  • Requires: Python >=3.10
  • Provides-Extra: dev
  • Development Status 3 - Alpha
  • 3 - Alpha
  • Intended Audience Developers Education Science/Research
  • Developers
  • Education
  • Science/Research
  • License OSI Approved :: MIT License
  • OSI Approved :: MIT License
  • Operating System OS Independent
  • OS Independent
  • Programming Language Python :: 3 Python :: 3.10 Python :: 3.11 Python :: 3.12 Python :: 3.13
  • Python :: 3
  • Python :: 3.10
  • Python :: 3.11
  • Python :: 3.12
  • Python :: 3.13
  • Topic Software Development :: Libraries :: Python Modules
  • Software Development :: Libraries :: Python Modules

Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

Uploaded Jun 12, 2026 Source

Built Distribution

Filter files by name, interpreter, ABI, and platform.

If you're not sure about the file name format, learn more about wheel file names.

Copy a direct link to the current filters

Uploaded Jun 12, 2026 Python 3

File details

Details for the file openmatchkit-0.3.0.tar.gz.

File metadata

  • Download URL: openmatchkit-0.3.0.tar.gz
  • Upload date: Jun 12, 2026
  • Size: 29.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

See more details on using hashes here.

Provenance

The following attestation bundles were made for openmatchkit-0.3.0.tar.gz:

Publisher: publish.yml on patilprashan246/openmatchkit

File details

Details for the file openmatchkit-0.3.0-py3-none-any.whl.

File metadata

  • Download URL: openmatchkit-0.3.0-py3-none-any.whl
  • Upload date: Jun 12, 2026
  • Size: 26.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

See more details on using hashes here.

Provenance

The following attestation bundles were made for openmatchkit-0.3.0-py3-none-any.whl:

Publisher: publish.yml on patilprashan246/openmatchkit

Source: Pypi.org