Development Status: This project is no longer undergoing active development. Please consider opening a pull request for any new features or bug fixes to be reviewed and merged.
Contents
- Installation
- Examples
- Get instances of all NHL teams for the 2018 season
- Print every NBA team's name and abbreviation
- Get a specific NFL team's season information
- Print the date of every game for a NCAA Men's Basketball team
- Print the number of interceptions by the away team in a NCAA Football game
- Get a Pandas DataFrame of all stats for a MLB game
- Find the number of goals a football team has scored
- Documentation
- Testing
Sportsipy is a free python API that pulls the stats from www.sports-reference.com and allows them to be easily be used in python-based applications, especially ones involving data analytics and machine learning.
Sportsipy exposes a plethora of sports information from major sports leagues in North America, such as the MLB, NBA, College Football and Basketball, NFL, and NHL. Sportsipy also now supports Professional Football (or Soccer) for thousands of teams from leagues around the world. Every sport has its own set of valid API queries ranging from the list of teams in a league, to the date and time of a game, to the total number of wins a team has secured during the season, and many, many more metrics that paint a more detailed picture of how a team has performed during a game or throughout a season.
The easiest way to install sportsipy is by downloading the latest released binary from PyPI using PIP. For instructions on installing PIP, visit PyPA.io for detailed steps on installing the package manager for your local environment.
Next, run:
pip install sportsipy
to download and install the latest official release of sportsipy on your machine. You now have the latest stable version of sportsipy installed and can begin using it following the examples below!
If the bleeding-edge version of sportsipy is desired, clone this repository using git and install all of the package requirements with PIP:
git clone https://github.com/roclark/sportsipy cd sportsipy pip install -r requirements.txt
Once complete, create a Python wheel for your default version of Python by running the following command:
python setup.py sdist bdist_wheel
This will create a .whl file in the dist directory which can be installed with the following command:
pip install dist/*.whl
The following are a few examples showcasing how easy it can be to collect an abundance of metrics and information from all of the tracked leagues. The examples below are only a miniscule subset of the total number of statistics that can be pulled using sportsipy. Visit the documentation on Read The Docs for a complete list of all information exposed by the API.
from sportsipy.nhl.teams import Teams
teams = Teams(2018)from sportsipy.nba.teams import Teams
teams = Teams()
for team in teams:
print(team.name, team.abbreviation)from sportsipy.nfl.teams import Teams
teams = Teams()
lions = teams('DET')from sportsipy.ncaab.schedule import Schedule
purdue_schedule = Schedule('purdue')
for game in purdue_schedule:
print(game.date)from sportsipy.ncaaf.boxscore import Boxscore
championship_game = Boxscore('2018-01-08-georgia')
print(championship_game.away_interceptions)from sportsipy.mlb.boxscore import Boxscore
game = Boxscore('BOS201806070')
df = game.dataframefrom sportsipy.fb.team import Team
tottenham = Team('Tottenham Hotspur')
print(tottenham.goals_scored)Two blog posts detailing the creation and basic usage of sportsipy can be found on The Medium at the following links:
The second post in particular is a great guide for getting started with sportsipy and is highly recommended for anyone who is new to the package.
Complete documentation is hosted on readthedocs.org. Refer to the documentation for a full list of all metrics and information exposed by sportsipy. The documentation is auto-generated using Sphinx based on the docstrings in the sportsipy package.
Sportsipy contains a testing suite which aims to test all major portions of code for proper functionality. To run the test suite against your environment, ensure all of the requirements are installed by running:
pip install -r requirements.txt
Next, start the tests by running py.test while optionally including coverage flags which identify the amount of production code covered by the testing framework:
py.test --cov=sportsipy --cov-report term-missing tests/
If the tests were successful, it will return a green line will show a message at the end of the output similar to the following:
======================= 380 passed in 245.56 seconds =======================
If the tests were successful (as indicated by the "passed" message), everything is working correctly. You're all set to use Sportsipy!
Troubleshooting Failed Tests:
If any tests failed, the output will indicate the number of failures and what went wrong. Don't worry! Here's an example of a failure output what you can do:
======================================== FAILURES =================================================================== ________________________________ test_team_statistics_failure ________________________________________________
- def test_team_statistics_failure():
- # Simulate a failed test by asserting false
> assert False, "Example assertion error: Failed to retrieve team statistics."
tests/test_sportsipy.py:20: _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
- def test_team_statistics_failure():
- # Simulate a failed test by asserting false
> assert False, "Example assertion error: Failed to retrieve team statistics." E AssertionError: Example assertion error: Failed to retrieve team statistics.
tests/test_sportsipy.py:21: AssertionError ======================= 379 passed, 1 failed in 245.56 seconds =======================
- Update Your Code: Make sure you have the latest version of Sportsipy installed. Sometimes, issues are fixed in newer releases.
- Check Your Environment: Ensure you're running Sportsipy in a supported environment. Refer to the documentation for the list of supported configurations.
- Creating an Issue on GitHub: If you're still experiencing problems, don't hesitate to create an issue on GitHub. Follow these steps: - Go to the [Sportsipy GitHub repository](https://github.com/roclark/sportsipy). - Click on the "Issues" tab. - Click the green "New issue" button. - Describe the problem you're facing in detail, including any error messages or relevant context. - Submit the issue, and the maintainers will investigate and assist you in resolving the issue.
By following these more detailed steps, you can troubleshoot any issues you encounter and get the support you need to make the most out of Sportsipy!