Skip to main content

NFL — PFF Developer API (api.pff.com, API key) — Other: ref_leagues–whoami

pff_api_ref_leagues​

List the leagues you can read, with their seasons and weeks

Endpoint URL: GET https://api.pff.com/v1/leagues

Valid URL: https://api.pff.com/v1/leagues

API ParameterPythonPatternRequiredNullableDescription

Returns​

return_parsed=True (default) — a tidy polars.DataFrame with the columns below; pass return_as_pandas=True for a pandas.DataFrame.

col_nametypedescription
abbreviationStringLeague abbreviation as the source lists it (e.g. NFL).
default_seasonFloat64Season the source API currently treats as the default for this league.
default_weekFloat64Week number the source API currently treats as the default for this league.
default_week_groupStringIdentifier of the week grouping (e.g., regular season or postseason phase) currently set as the league default.
idFloat64Numeric league id from the source API (PFF: 1 = NFL).
nameStringLeague display name as the source lists it (PFF: 'Pro Football').
seasonsListNested list (stringified) of the seasons the source publishes for the league.
slugStringURL slug of the league on premium.pff.com (e.g. nfl).
week_groupsListNested list of week-group objects (phase label and week span) defined for the league.
weeksListNested list of week objects available for the league.

return_parsed=False — The decoded JSON body. /v1 routes return the Premium Stats envelope ({report_slug: rows}); /v2 routes return {..meta.., columns, rows}..

Raises​

ExceptionDescription
RuntimeErrorNo PFF API key (pass api_key= or set PFF_API_KEY).
NoDataErrorThe host answered 404 -- the requested resource does not exist. PFF answered 404 (no such route, report or team).
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty. The request was refused or failed (401/403/429/5xx) -- the answer is unknown, never an empty frame.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help. PFF rejected the parameters (400 invalid_parameter / 422).

Example​

pff_api_ref_leagues()

pff_api_ref_games​

List game results for a league, season and week

Endpoint URL: GET https://api.pff.com/v1/games

Valid URL: https://api.pff.com/v1/games?league=nfl&season=2022&week=1

API ParameterPythonPatternRequiredNullableDescription
leagueleagueYLeague slug, and the FIRST positional argument of every command that takes one — every command except the facet leaderboards, where --league stays a flag because --game alone is a complete request.
seasonseasonYSeason, as a four-digit year, taken as a positional argument.
weekweekYWeek, and the THIRD positional argument of games — the one command that takes a single week number rather than a comma-separated list.
franchise_idfranchise_idYFranchise (team) id.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame with the columns below; pass return_as_pandas=True for a pandas.DataFrame.

col_nametypedescription
away_franchise_idFloat64PFF franchise id of the away team.
away_teamListAway team object (JSON-stringified in the tidy frame).
has_statsBooleanWhether PFF has published stats for the game.
home_franchise_idFloat64PFF franchise id of the home team.
home_teamListHome team object (JSON-stringified in the tidy frame).
idFloat64PFF game id (integer join key).
leagueListNested league object of the game (stringified) with the PFF league id, name and abbreviation (e.g. NFL).
league_idFloat64PFF league id (integer).
lock_statusStringData lock/publish status for the game.
scoreListNested final-score object of the game (stringified) with away_team and home_team points.
seasonFloat64Season (starting year) of the game.
stadium_idFloat64PFF stadium identifier for the game venue.
startStringKickoff timestamp (ISO 8601 string).
weekFloat64Week number of the game.

return_parsed=False — The decoded JSON body. /v1 routes return the Premium Stats envelope ({report_slug: rows}); /v2 routes return {..meta.., columns, rows}..

Raises​

ExceptionDescription
RuntimeErrorNo PFF API key (pass api_key= or set PFF_API_KEY).
NoDataErrorThe host answered 404 -- the requested resource does not exist. PFF answered 404 (no such route, report or team).
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty. The request was refused or failed (401/403/429/5xx) -- the answer is unknown, never an empty frame.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help. PFF rejected the parameters (400 invalid_parameter / 422).

Example​

pff_api_ref_games(league='nfl', season=2022, week=1)

pff_api_ref_players​

Search the player directory by name or id

Endpoint URL: GET https://api.pff.com/v1/players

Valid URL: https://api.pff.com/v1/players?league=nfl&name=burrow

API ParameterPythonPatternRequiredNullableDescription
leagueleagueYLeague slug, and the FIRST positional argument of every command that takes one — every command except the facet leaderboards, where --league stays a flag because --game alone is a complete request.
ididYExact player-id lookup, ref-players only.
namenameYFree-text player-name search, ref-players only.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame with the columns below; pass return_as_pandas=True for a pandas.DataFrame.

col_nametypedescription
collegeStringCollege the player attended, as the source lists it.
current_classStringPlayer's current college class designation (e.g., Freshman, Senior), per PFF.
current_eligible_yearFloat64Year the player is or was first draft-eligible, per PFF.
dobStringPlayer's date of birth (YYYY-MM-DD).
draftListNested draft-selection details for the player (year, round, pick, and franchise) as returned by the source API.
first_nameStringPlayer's first name as the source lists it.
heightFloat64Player's height as the source encodes it (PFF uses feet and inches without a separator, 602 = 6'02"; others use inches or centimetres).
idFloat64PFF numeric player id, the key of the player-scoped endpoints.
jersey_numberStringJersey number as a string.
last_nameStringPlayer's last name as the source lists it.
positionStringPosition abbreviation as the source lists it (e.g. QB, WR).
speedFloat6440-yard-dash time in seconds as recorded by PFF.
teamListCurrent team of the player as the source ships it (a nested team object, stringified, or a team code).
weightFloat64Player's weight as the source lists it (pounds for US sources).

return_parsed=False — The decoded JSON body. /v1 routes return the Premium Stats envelope ({report_slug: rows}); /v2 routes return {..meta.., columns, rows}..

Raises​

ExceptionDescription
RuntimeErrorNo PFF API key (pass api_key= or set PFF_API_KEY).
NoDataErrorThe host answered 404 -- the requested resource does not exist. PFF answered 404 (no such route, report or team).
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty. The request was refused or failed (401/403/429/5xx) -- the answer is unknown, never an empty frame.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help. PFF rejected the parameters (400 invalid_parameter / 422).

Example​

pff_api_ref_players(league='nfl', name='burrow')

pff_api_whoami​

Show what this API believes about the current credential

Endpoint URL: GET https://api.pff.com/v1/auth/whoami

Valid URL: https://api.pff.com/v1/auth/whoami

API ParameterPythonPatternRequiredNullableDescription

Returns​

Show what this API believes about the current credential

Raises​

ExceptionDescription
RuntimeErrorNo PFF API key (pass api_key= or set PFF_API_KEY).
NoDataErrorThe host answered 404 -- the requested resource does not exist. PFF answered 404 (no such route, report or team).
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty. The request was refused or failed (401/403/429/5xx) -- the answer is unknown, never an empty frame.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help. PFF rejected the parameters (400 invalid_parameter / 422).

Example​

pff_api_whoami()