/soccer-cli

:soccer: Football scores for hackers. :computer: A command line interface for all the football scores.

Primary LanguagePythonMIT LicenseMIT

Soccer CLI

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

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

Install

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:

export SOCCER_CLI_API_TOKEN="<YOUR_API_TOKEN>"

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
<YOUR_API_TOKEN>

Note:

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

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

Specifically for the Windows terminal, by default the terminal may be limited in size(width) even when enlarged, However, this can be dealt with by running the commands

mode 800 for more info. please check this stackoverflow post

Dot notation interface

from resources import Soccer
soccer = Soccer()
# to get all competitions
response = soccer.competitions().query.get()

# to get a single competition
response = soccer.competitions(2021).query.get()
# to apply filters i.e. say the areas we want England whose id is 2072
response = soccer.competitions().query.filter(areas=2072).get()

# a few of subresources endpoints within competitions
soccer.competitions(2021).scorers.query.get()
soccer.competitions(2021).scorers.query.filter(limit=20).get()
soccer.competitions(2021).matches.query.get()

# Match resource
response = soccer.matches().query.filter(status='FINISHED').get()

# players resource
soccer.players(1).matches.query.filter(status='SCHEDULED').get()

# areas resource
soccer.areas().query.get()

# teams resource
soccer.teams(57).query.get()

Usage

Competition Resource commands

get all competitions
$ soccer competitions

filters: areas, and plans

areas
$ soccer competitions --areas 2072 #  2072 is england's area id
plan(payment pLAN)

usually if you are not subscribed to any premium plans, you'r requests will be automatically handled as TIER_ONE

$soccer competitions --plan TIER_ONE # TIER_ONE has access to 14 competitions
get specific competition/league info
$ soccer competitions --id 2021 standings # 2021 is the competition id for English Premier League
get teams in a certain competition(league)
$ soccer competitions --id 2021 teams

filters: season and stage

season
$ soccer competitions --id 2021 teams --season 2017 # season is the year that the league starts in
stage
$ soccer competitions --id 2021 teams --stage <stage>

get a specific competition's standings
$ soccer competitions --id 2021 standings

filters: standingtype

standingtType as standingtype
$ soccer competitions --id 2021 standings --standingtype HOME

the standing types are case insesitive when fed in through the shell otherwise should be strictly upper.

get a specific competition's matches

$ soccer competitions --id 2021 matches

filters : dates(from and to), stage, status, matchday, group, and season

dates
$ soccer competitions --id 2021 matches --from 2018-10-18 --to 2018-10-20
status

Can use this to get the live matches within a certain competition

$ soccer competitions --id 2021 matches --status LIVE

hope you get the idea and can comfortably use the other filters and a combination of any to specify your query

get scorers within a competition

$ soccer competition --id 2021 scorers
$ soccer competition --id 2021 scorers --limit 20 # to get info on the top 20 scorers of the English premier league

Team resource commands

specific team info

$ soccer teams --id <id>

Matches subresource

used to get match records on which team of given id participated in

$ soccer teams --id 66 matches  #  66 happens to be Manchester United's team id
filters : dates(from and to), status, venue, limit
$ soccer teams --id 66 matches --from 2018-09-23 --to 2018-10-01
$ soccer teams --id 66 matches --status CANCELLED
$ soccer teams --id 66 matches --venue <venue>

Match Resource commands

Get upcoming fixtures

$ soccer matches --status SCHEDULED

all mathes and specific match

$ soccer matches
$ soccer matches --id <match_id>
Match resource fillters : competitions, dates, status
soccer matches --competitions 2000 # world cup matches
soccer matches --competitions 2021 --competitions 2000 #Request for matches from 2 competitions

Player Resource commands

get specific player info

$ soccer players --id  <id> # <id> is the id of player of interest

get matches that player played in

$ soccer players --id <player_id>
filters : dates(from and to), status, competitions/leagues, limit
$ soccer players --id 1 --competitions 2021 --status FINISHED

Areas Resource commands

get area info

$ soccer areas # retrieves info for all areas in api
$ soccer areas --id 2000 # retrieves info WC whose id is 2000

Help

$ 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 And upto 131+ more competitions oferred by the API, supports all competitions offered by the api

Tests

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

Todo

  • replace demo sections
  • add how to get ids section
  • integrate the writer with updated code
  • add a developer interface : to use dot notation and direct method calls as opposed to cli
  • id listing
  • predictive analytical statistics
  • 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.

Licence

Open sourced under MIT License

Contributions

This is one of the simplest projects out here on github and it does require lots of help so feel free to branch out and send pull request, or raise any issues that may better the project in the Issues section. Thanks.