Welcome to scorecard’s documentation!

A python library for collegescorecard.ed.gov

Contents:

Installation

The best way to install the library is by using pip.

pip install college-scorecard

You can also install by cloning the repository from git.

git clone https://github.com/ahoodatheguy/scorecard.git

Or install the repository directly from Github.

pip install git+https://github.com/ahoodatheguy/scorecard.git

Getting Started

Learn how to use scorecard.

API Access

An API key is required to use the college scorecard API. You can apply for one for free here.

Starter Code

from scorecard.api import ScoreCard

sc = ScoreCard(api_key)

for college in sc.search('Howard'):
        print(str(college))

This example will search for and return the name of every college with the name “Howard” in it and return it’s name and id.

If you know a specific colleges id, you can query that one specifically.

from scorecard.api import ScoreCard

sc = ScoreCard(api_key)

print(sc.get_by_id(131520))

Module Reference:

scorecard

api module

Interface with the collegescorecard API.

class api.ScoreCard(API_KEY: str)

Bases: object

This is the main class used to search for colleges and their data.

Parameters:

API_KEY – The API key used to interact with college scorecards API.

get_by_id(id: int, year='latest') → College

Query a college by it’s id.

Parameters:

  • id – The id of the college you want to search.

  • year (str, optional) – What year to retrieve the data from, defaults to latest availible year.

search(name: Optional[str] = None, page=0, per_page=20, year='latest', hbcu: Optional[bool] = None, size_range: list = [0, None], ownership: Optional[int] = None) → List[College]

Search for a college by name.

Parameters:

  • name (str, optional) – The name of the target college

  • page (int, optional) – What page to query the data from

  • per_page (int, optional) – How many results to show per page, defaults to 20

  • year (str, optional) – What year to retrieve the data from, defaults to latest availible year

  • hbcu (bool, optional) – Filter results by whether or not it’s an HBCU

  • size_range (list, optional) – Limit results based on student population. List is structured as [min, max]

  • ownership (int, optional) – Filter based on the ownership status of the college

exceptions module

exception exceptions.InvalidAPIKey(message='Attempt to connect to collegescorecard with an invalid API key')

Bases: Exception

exception exceptions.MissingAPIKey(message='Attempt to connect to collegescorecard with no API key')

Bases: Exception

objects module

class objects.Admissions(data)

Bases: object

Data relating to a colleges admissions

property act_scores: Dict[str, int]

Midpoint of the ACT scores

property rate: float

Admission rate

property sat_scores: Dict[str, int]

Midpoint of SAT scores at the institution

property test_required: bool

Test score requirements for admission

class objects.College(data: dict, year: str)

Bases: object

property accreditor: str

Accreditor for institution

property admissions: Admissions
property cost: Tuition
property endowment_begin: int

Value of school’s endowment at the beginning of the fiscal year

property endowment_end: int

Value of school’s endowment at the end of the fiscal year

property location: dict

Return the state and city of the college.

property name: str

Institution name

property operating: bool

Flag for currently operating institution

property ownership: int

Control of institution, returns either 1, 2, or 3.

1 - Public

2 - Private, Nonprofit

3 - Private, for-profit

property region: int

Return the colleges region code.

property student: StudentBody
class objects.StudentBody(data)

Bases: object

property gender_breakdown: Dict[str, float]

Return the gender breakdown of a college.

property graduate_size: int

Number of graduate students

property racial_diversity: Dict[str, float]

Racial diversity statistics, rounded to 2 decimal places.

property undergrad_size: int

Enrollment of undergraduate certificate/degree-seeking students

class objects.Tuition(data: dict)

Bases: object

property booksupply: int

Cost of attendance: estimated books and supplies

get_tuition(in_state=True) → int

Average cost of a year at the college.

Parameters:

in_state (bool, optional) – Return a colleges in-state tuition or out of state tuition, defaults to true.

property overall_median: int

Overall median for average net price

property room_and_board: float

Cost of attendance: on-campus room and board

Indices and tables