Python Quickstart

The official pearatings package

Official libraries

pearatings is the official client, and Python is the only language with one so far. It wraps every endpoint in a plain function and returns tables as pandas DataFrames. From any other language, call the REST API directly: see the API Reference.

Install the package

Terminal
pip install pearatings

Get a key on the pricing page, then store it in an environment variable so it stays out of your code. Use single quotes if the key has a ! in it.

Terminal
export PEAR_API_KEY='your-key'

You can pass it instead: Pear(api_key="your-key").

Get ratings

This is the same data as GET /v1/baseball/d1/ratings, as a DataFrame with one row per team.

Python
from pearatings import Pear

pear = Pear()                        # reads PEAR_API_KEY

ratings = pear.ratings()             # D1 baseball, current
print(ratings.head())
print(ratings.attrs["date"])         # the day the ratings are from

Every function takes sport ("baseball" by default, or "softball") and division ("d1" by default, "d2", "d3", "naia") as keywords, unless it exists for one division only or takes a game id.

Python
pear.ratings(sport="softball", division="d2")
pear.preseason(2027)                          # preseason ratings
pear.stats(2025)                              # PEAR team numbers, end of 2025

Games, teams and players

Python
pear.games("2026-04-18")                      # that day's games, PEAR's line and win probability
pear.matchup("LSU", "Florida", neutral=True)  # any two teams
pear.team_schedule("LSU", 2026)["schedule"]   # every game of a team's season

roster = pear.roster("LSU", 2026)             # Plus
pear.player(roster["player_id"].iloc[0])      # one player, game by game

game_id = pear.games("2026-04-18")["game_id"].iloc[0]
pear.box_score(game_id)["batting"]            # Pro
pear.play_by_play(game_id)                    # Pro: every play, with win probability

help(pear.games) prints any function's details, including the tier it needs when that is more than Free.

What comes back

  • One table comes back as a DataFrame. The rest of the response (the data's date, the season, totals) is in df.attrs.
  • Anything else comes back as a dict in which every list of records is a DataFrame.
  • Nested fields become dotted columns: record.wins, stats.PA.
  • pear.get("baseball/d1/ratings") and pear.post(path, body) return the raw JSON of any endpoint.

Your account

Python
pear.account()           # tier, limits, calls used this month
pear.billing_portal()    # a link to change tier, update your card or cancel

Errors

Every error is a subclass of pearatings.PearError and carries .status_code.

ErrorWhen
AuthenticationErrorThe key is missing, wrong, or its subscription has lapsed.
TierErrorThe function needs a higher tier; .required_tier names it.
RateLimitErrorYou are over a limit; .retry_after is the seconds to wait.
NotFoundErrorAn unknown team, game, player or season.
InvalidRequestErrorA parameter is not valid.
APIErrorAnything else, such as data that is not available out of season.
Python
import time
from pearatings import Pear, RateLimitError

pear = Pear()
try:
    schedule = pear.schedule(2026)
except RateLimitError as err:
    time.sleep(err.retry_after)
    schedule = pear.schedule(2026)

More

The full list of functions is on the package's PyPI page. The package is open source under the MIT license.

Advertisement