boknows

Get NCAA stats and figures without the hassle of stats.ncaa.org

Build status

Features

  • Simple Web API to serve team and player stats
  • Basic CSV export, cleanup and caching
  • Barebones command line interface

Table of contents

Installation

Clone the library to run a Web API locally:

git clone https://github.com/nbedi/boknows.git

Install the Python library for command line use:

pip install --pre boknows

Tutorial

Web API

boknows uses Flask to serve NCAA statistics as a Web API. In the boknows folder, simply run

python boknows/api.py

to start the Flask app.

Reference the Web API documentation for endpoints.

Command Line Interface

The command line interface is extremely basic at the moment. It is only connected to the csv_dump function to write a stream of NCAA statistics to a CSV file.

To use default settings specified in the csv_dump documentation, simply run:

boknows

The Command line interface documentation specifies optional arguments.

Web API

boknows uses Flask to serve NCAA statistics as a basic Web API. The api connects to the boknows.utils.get_ncaa_data() function to return stats and store data for rudimentary caching.

GET /api/v1.0/(string: sport_code)/(string: div)/players/(string: player_name)

Returns latest data of specified player. Output is a JSON dictionary with ‘response’ as the key and a list of objects for each player as the value. Warning: many players have blanks in columns.

Parameters:
  • sport_code – NCAA code for desired sport. Ex: ‘MBB’ is Men’s Basketball
  • div – NCAA division. Ex: ‘1’ for Division 1.
  • player_name – Player name with spaces removed.
GET /api/v1.0/(string: sport_code)/(string: div)/teams/(string: team_name)

Returns latest data of specified team. Output is a JSON dictionary with ‘response’ as the key and a list of objects for each team as the value.

Parameters:
  • sport_code – NCAA code for desired sport. Ex: ‘MBB’ is Men’s Basketball
  • div – NCAA division. Ex: ‘1’ for Division 1.
  • team_name – NCAA school name with spaces removed.
GET /api/v1.0/(string: sport_code)/(string: div)/players

Returns latest data of all players. Output is a JSON dictionary with ‘response’ as the key and a list of objects for each player as the value. Warning: many players have blanks in columns.

Parameters:
  • sport_code – NCAA code for desired sport. Ex: ‘MBB’ is Men’s Basketball
  • div – NCAA division. Ex: ‘1’ for Division 1.
GET /api/v1.0/(string: sport_code)/(string: div)/teams

Returns latest data of all teams. Output is a JSON dictionary with ‘response’ as the key and a list of objects for each team as the value.

Parameters:
  • sport_code – NCAA code for desired sport. Ex: ‘MBB’ is Men’s Basketball
  • div – NCAA division. Ex: ‘1’ for Division 1.

Command line interface

To start, the command line interface is just a wrapper on the csv_dump function. There are no additional commands. Default arguments will be used when optional arguments are not specified.

optional arguments:

-s, --sport Specify NCAA sport id
-y, --year Specify academic year
-w, --weeks Specify NCAA id for reporting weeks
-d, --div Specify NCAA division
-a, --stat Specify NCAA statistics id

boknows.utils

boknows.utils.csv_cleanup(content)

Cleans up the csv output from NCAA stats. Separates different tables into individual strings.

Returns a tuple with filename and csv content.

Parameters:content – Original output from NCAA stats
boknows.utils.csv_dump(dir_path='dump', sport_code='MBB', academic_year='latest', rpt_weeks='latest', div='1', stat_seq='team')

Dumps a csv file according to inputs to specified path. Most inputs are based on arbitrary NCAA codes that users should not have to know (except for maybe sport_code).

Parameters:dir_path – Path to directory to dump CSV files in. Defaults to directory called ‘dump’

Other inputs documented in boknows.utils.ncaa_request().

boknows.utils.get_ncaa_data(sport_code, div, stat_seq, academic_year='latest', rpt_weeks='latest')

Gets NCAA data in CSV format with minimal input. Uses rudimentary caching by simply loading from file if it has already been created and stored in default directory.

All inputs defined in boknows.utils.ncaa_request() function. Defaults academic_year and rpt_weeks to ‘latest’.

boknows.utils.ncaa_request(rpt_type, sport_code, academic_year, rpt_weeks, div, stat_seq)

Makes request to NCAA web application at http://web1.ncaa.org/stats/StatsSrv/rankings.

Parameters:
  • rpt_type – Format of response. Can be HTML, ASCII, PDF or CSV.
  • sport_code – NCAA code for desired sport.
  • academic_year – Numerical four digit academic year or ‘latest’. Earliest input is 2002.
  • rpt_weeks – Numerical NCAA code for end week of returned stats or ‘latest’.
  • div – NCAA division.
  • stat_seq – NCAA code for specific stats requested. Generic terms ‘team’ and ‘player’ will return all team or individual stats.