Package: understatapi
understatAPIThis is a python API for scraping data fromunderstat.com. Understat is a website with football data for 6 european leagues for every season since 2014/15 season. The leagues available are the Premier League, La Liga, Ligue 1, Serie A, Bundesliga and the Russian Premier League.NOTEI am not affiliated with understat.com in any wayInstallationTo install the package runpipinstallunderstatapiIf you would like to use the package with the latest development changes you can clone this repo and install the packagegitclonegit@github.com:collinb9/understatAPIunderstatAPIcdunderstatAPI
pythonsetup.pyinstallGetting startedNOTEThis package is in early stages of development and the API is likely to changeThe API contains endpoints which reflect the structure of the understat website. Below is a table showing the different endpoints and the pages on understat.com to which they correspondEndpointWebpageUnderstatClient.leaguehttps://understat.com/league/<league_name>UnderstatClient.teamhttps://understat.com/team/<team_name>/<season>UnderstatClient.playerhttps://understat.com/player/<player_id>UnderstatClient.matchhttps://understat.com/match/<match_id>Every mwthod in the public API corresponds to one of the tables visible on the understat page for the relevant endpoint.
Each method returns JSON with the relevant data. Below are some examples of how to use the API. Note how theleague()andteam()methods can accept the names of leagues and teams respectively, butplayer()andmatch()must receive an id number.fromunderstatapiimportUnderstatClientunderstat=UnderstatClient()# get data for every player playing in the Premier League in 2019/20league_player_data=understat.league(league="EPL").get_player_data(season="2019")# Get the name and id of one of the playerplayer_id,player_name=league_player_data[0]["id"],league_player_data[0]["player_name"]# Get data for every shot this player has taken in a league match (for all seasons)player_shot_data=understat.player(player=player_id).get_shot_data()fromunderstatapiimportUnderstatClientunderstat=UnderstatClient()# get data for every league match involving Manchester United in 2019/20team_match_data=understat.team(team="Manchester_United").get_match_data(season="2019")# get the id for the first match of the seasonmatch_id=match_data[0]["id"]# get the rosters for the both teams in that matchroster_data=understat.match(match=match_id).get_roster_data()You can also use theUnderstatClientclass as a context manager which closes the session after it has been used, and also has some improved error handling. This is the recommended way to interact with the API.fromunderstatapiimportUnderstatClientwithUnderstatClient()asunderstat:team_match_data=understat.team(team="Manchester_United").get_match_data(season="2019")For a full API reference, seethe documentationContributingIf you find any bugs in the code or have any feature requests, please make an issue and I'll try to address it as soon as possible. If you would like to implement the changes yourself you can make a pull requestClone the repogit clone git@github.com:collinb9/understatAPICreate a branch to work offgit checkout -b descriptive_branch_nameMake and commit your changesPush your changesgit pushCome back to the repo on github, and click on Pull requests -> New pull requestBefore a pull request can be merged the code will have to pass a number of checks that are run using CircleCI. These checks areCheck that the code has been formatted usingblackLint the code usingpylintCheck type annotations usingmypyRun the unit tests and check that they have 100% coverageThese checks are in place to ensure a consistent style and quality across the code. To check if the changes you have made will pass these tests runpipinstall-rrequirements.txt
pipinstall-rtest_requirments.txt
pipinstall-rdocs_requirments.txt
chmod+xci/run_tests.sh
ci/run_tests.shDon't let these tests deter you from making a pull request. Make the changes to introduce the new functionality/bug fix and then I will be happy to help get the code to a stage where it passes the tests.VersioningThe versioning for this project follows thesemantic versioningconventions.TODOAdd asynchronous support