⚽️ Football scores for hackers. 💻 A command line interface for all the football scores.
Switch branches/tags
Nothing to show
Clone or download
Latest commit 8838ca9 Aug 7, 2018


Soccer CLI

PyPI version Join the chat at https://gitter.im/architv/soccer-cli

Soccer for Hackers - a CLI for all the football scores.


An API key from football-data.org will be required and you can register for one here.

Using pip

$ pip install soccer-cli

Set your API key in an environment variable SOCCER_CLI_API_TOKEN

For example:


Build from source

$ git clone https://github.com/architv/soccer-cli.git
$ cd soccer-cli
$ python setup.py install

You can set the API key using an environment variable as shown above or create a file .soccer-cli.ini in your home folder (/home/username/.soccer-cli.ini) that contains only your API token, such that:

$ cat /home/username/.soccer-cli.ini


Currently supports Linux, Mac OS X, NetBSD, FreeBSD and Windows.

To get colorized terminal output on Windows, make sure to install ansicon and colorama.


Get standings for a league

$ soccer --standings --league=PL # PL is the league code for English Premier League

Get scores for a particular team

$ soccer --team=MUFC # MUFC is the team code for Manchester United
$ soccer --team=PSG --time=10 # scores for all the Paris Saint-Germain games over the past 10 days

Get upcoming fixtures

$ soccer --time 5 --upcoming # get upcoming fixtures for next 5 days
$ soccer --time 5 --upcoming --use12hour # upcoming fixture for next 5 days with timings in 12 hour format

Get scores for live games

$ soccer --live

Get scores for a particular league

$ soccer --league=BL # BL is the league code for Bundesliga
$ soccer --league=FL --time=15 # get scores for all the French Ligue games over the past 15 days

Get information about players of a team

$ soccer --team=JUVE --players

Get scores for all seven leagues with a set time period

$ soccer --time=10 # get scores for all the seven leagues over the past 10 days

Get the output in csv or json

$ soccer --league PL --standings --csv # prints the output in csv format
$ soccer --league PL --standings --json # prints the output in json format

Store the ouput in a file

$ soccer --league PL --standings --csv -o 'standings.csv' # stores the ouput in scv format in `standings.csv`


$ soccer --help

List of supported leagues and their league codes

  • Europe:
    • CL: Champions League
  • England:
    • PL: Premier League
    • EL1: League One
  • France:
    • FL: Ligue 1
    • FL2: Ligue 2
  • Germany:
    • BL: Bundesliga
    • BL2: 2. Bundesliga
    • BL3: 3. Liga
  • Italy:
    • SA: Serie A
  • Netherlands:
    • DED: Eredivisie
  • Portugal:
    • PPL: Primeira Liga
  • Spain:
    • LLIGA: La Liga
    • SD: Segunda Division

Team and team codes

For a full list of supported team and team codes see this.


To run testing suite from root of repo

$ python -m unittest discover tests

To run specific test file (in this case the tests in test_request_handler.py)

$ python -m unittest tests.test_request_handler




Live scores

Team scores

Output in json format


  • Enable cache
  • Add more test cases
  • Add fixtures for UEFA Champions League
  • Add league filter for live scores
  • Color coding for Europa league and differentiation between straight CL and CL playoff spots, and the same for EL spots
  • Add support for team line up
  • A built in watch feature so you can run once with --live and just leave the program running.


Open sourced under MIT License


If you like my work, please support the project by donating.