Skip to main content

NFL — PFF Developer API (api.pff.com, API key) — Player: receiving–special

pff_api_player_receiving_summary​

Receiving summary for one player

Endpoint URL: GET https://api.pff.com/v1/player/receiving/summary

Valid URL: https://api.pff.com/v1/player/receiving/summary?league=nfl&season=2022&player_id=28022

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.
weekweekYWeek filter.
player_idplayer_idYPlayer id, taken as a positional argument.
careercareerYCareer-aggregate toggle, on the player report operations 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
targetsInt64Times targeted.
grades_offenseFloat64PFF overall offense grade (0-100).
game_idInt64PFF game id of the game (integer join key).
yards_after_catch_per_receptionFloat64Average yards after the catch per reception.
grades_pass_routeFloat64PFF receiving/route grade (0-100).
weekInt64Week number of the game, as PFF numbers weeks.
statusString"S" when the player started the game; PFF owns the value set.
yprrFloat64Yards per route run.
wide_snapsInt64Receiving snaps aligned out wide.
fumblesInt64Fumbles by the player after the catch.
first_downsInt64Receptions that converted a first down.
jersey_numberStringJersey number the player wore in the game (string; zero-padded, e.g. "09").
inline_snapsInt64Receiving snaps aligned inline, tight to the formation.
away_team_nameStringAbbreviation of the away team (e.g. "LV").
contested_targetsInt64Contested targets.
inline_rateFloat64Share of receiving snaps aligned inline, tight to the formation.
contested_catch_rateFloat64Percentage of PFF-charted contested targets caught.
yardsInt64Receiving yards.
player_franchise_idInt64PFF franchise id of the team the player played for in the game.
receptionsInt64Passes caught by the receiver.
targeted_qb_ratingFloat64NFL passer rating on throws targeting the player.
interceptionsInt64Interceptions on passes targeting the player.
caught_percentFloat64Percentage of targets caught.
positive_epa_playsInt64Plays with positive expected points added (positive_epa_percent = positive_epa_plays / plays_with_epa x 100).
drop_rateFloat64Share of catchable targets the player dropped.
grades_hands_dropFloat64PFF hands/drop grade (0-100).
slot_rateFloat64Share of receiving snaps aligned in the slot.
plays_with_epaInt64Plays with an expected-points-added value, the denominator of positive_epa_percent.
slot_snapsInt64Receiving snaps aligned in the slot.
penaltiesInt64Penalties charged to the player over the covered span.
wide_rateFloat64Share of receiving snaps aligned out wide.
pass_block_rateFloat64Share of pass-play snaps spent pass blocking.
declined_penaltiesInt64Penalties committed by the player that were declined.
route_rateFloat64Share of pass-play snaps on which the player ran a route.
dropsInt64Dropped passes.
positionStringPFF position code the player was charted at in the game (e.g. QB, HB, WR, T, LB, K).
grades_hands_fumbleFloat64PFF ball-security (hands/fumble) grade, 0-100.
longestInt64Longest reception in yards.
pass_blocksInt64Pass-play snaps spent pass blocking.
away_franchise_idInt64PFF franchise id of the away team.
routesInt64Pass routes run by the receiver.
pass_playsInt64Pass-play snaps.
yards_per_receptionFloat64Average yards per reception.
targets_percentFloat64Targets per route run, as a percentage (targets / routes x 100).
positive_epa_percentFloat64Percentage of the receiver's plays with an EPA value (in practice their routes run) producing positive expected points added (positive_epa_plays / plays_with_epa x 100).
contested_receptionsInt64Contested catches made.
yards_after_catchInt64Yards after the catch.
home_franchise_idInt64PFF franchise id of the home team.
home_team_nameStringAbbreviation of the home team (e.g. "NE").
avg_depth_of_targetFloat64Average depth of target in yards downfield.
epaFloat64Expected points added per target to the player, as computed by PFF (an average such as -0.27, not a total).
avoided_tacklesInt64Tackles avoided after the catch.
player_idInt64PFF player id (integer join key) of the player the report is about.
touchdownsInt64Receiving touchdowns.
game_away_franchise_idInt64Repeats away_franchise_id from the row's nested game object: PFF franchise id of the away team.
game_away_team_nameStringRepeats away_team_name from the row's nested game object: Abbreviation of the away team (e.g. "LV").
game_game_idInt64Repeats game_id from the row's nested game object: PFF game id of the game (integer join key).
game_home_franchise_idInt64Repeats home_franchise_id from the row's nested game object: PFF franchise id of the home team.
game_home_team_nameStringRepeats home_team_name from the row's nested game object: Abbreviation of the home team (e.g. "NE").
game_player_franchise_idInt64Repeats player_franchise_id from the row's nested game object: PFF franchise id of the team the player played for in the game.
game_positionStringRepeats position from the row's nested game object: PFF position code the player was charted at in the game (e.g. QB, HB, WR, T, LB, K).
game_statusStringRepeats status from the row's nested game object: "S" when the player started the game; PFF owns the value set.
game_weekInt64Repeats week from the row's nested game object: Week number of the game, as PFF numbers weeks.
league_idInt64PFF league id (1 = NFL, 2 = NCAA), filled from the report's subject.
seasonInt64Season (starting year) of the report, filled from the report's subject.

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_player_receiving_summary(league='nfl', player_id=28022, season=2022)

pff_api_player_defense_summary​

Defense summary for one player

Endpoint URL: GET https://api.pff.com/v1/player/defense/summary

Valid URL: https://api.pff.com/v1/player/defense/summary?league=nfl&season=2022&player_id=28022

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.
weekweekYWeek filter.
player_idplayer_idYPlayer id, taken as a positional argument.
careercareerYCareer-aggregate toggle, on the player report operations 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
targetsInt64Passes thrown into the player's coverage (targets allowed).
game_idInt64PFF game id of the game (integer join key).
interception_touchdownsInt64Touchdowns scored on interception returns.
weekInt64Week number of the game, as PFF numbers weeks.
forced_fumblesInt64Forced fumbles.
missed_tacklesInt64Missed tackles.
statusString"S" when the player started the game; PFF owns the value set.
catch_rateFloat64Completion percentage allowed on targets into the player's coverage.
tacklesInt64Total tackles made by the defender.
jersey_numberStringJersey number the player wore in the game (string; zero-padded, e.g. "09").
away_team_nameStringAbbreviation of the away team (e.g. "LV").
snap_counts_offballInt64Snaps aligned as an off-ball linebacker.
snap_counts_boxInt64Snaps aligned in the box.
sacksInt64Sacks credited.
snap_counts_pass_rushInt64Pass-rush snaps played.
snap_counts_dlInt64Snaps aligned on the defensive line.
grades_tackleFloat64PFF tackling grade, 0-100.
yardsInt64Receiving yards allowed in the player's coverage.
player_franchise_idInt64PFF franchise id of the team the player played for in the game.
receptionsInt64Receptions allowed in the player's coverage.
grades_coverage_defenseFloat64PFF coverage grade (0-100).
hurriesInt64Quarterback hurries recorded.
interceptionsInt64Interceptions made in coverage.
snap_counts_coverageInt64Coverage snaps played.
snap_counts_dl_over_tInt64Defensive-line snaps aligned head-up over the offensive tackle.
snap_counts_dl_a_gapInt64Defensive-line snaps aligned in the A gap.
fumble_recoveriesInt64Opponent fumbles recovered by the player.
grades_run_defenseFloat64PFF run-defense grade (0-100).
snap_counts_cornerInt64Snaps aligned at outside cornerback.
hitsInt64Quarterback hits recorded by the player.
penaltiesInt64Penalties charged to the player over the covered span.
batted_passesInt64Passes batted down at the line of scrimmage.
stopsInt64Tackles that constitute an offensive failure ("stops").
declined_penaltiesInt64Penalties committed by the player that were declined.
total_pressuresInt64Total quarterback pressures (sacks + hits + hurries).
positionStringPFF position code the player was charted at in the game (e.g. QB, HB, WR, T, LB, K).
fumble_recovery_touchdownsInt64Touchdowns scored on fumble recoveries.
longestInt64Longest completion allowed, in yards.
away_franchise_idInt64PFF franchise id of the away team.
snap_counts_slotInt64Snaps aligned in the slot.
missed_tackle_rateFloat64Share of tackle attempts the player missed.
grades_defenseFloat64PFF overall defense grade (0-100).
yards_per_receptionFloat64Average yards allowed per reception.
grades_defense_penaltyFloat64PFF defensive penalty grade, 0-100.
safetiesInt64Safeties recorded by the player.
snap_counts_defenseInt64Total defensive snaps played.
yards_after_catchInt64Yards after the catch allowed in the player's coverage.
home_franchise_idInt64PFF franchise id of the home team.
snap_counts_dl_b_gapInt64Defensive-line snaps aligned in the B gap.
home_team_nameStringAbbreviation of the home team (e.g. "NE").
pass_break_upsInt64Passes broken up.
qb_rating_againstFloat64NFL passer rating allowed on targets into the player's coverage.
snap_counts_run_defenseInt64Run-defense snaps played.
tackles_for_lossInt64Tackles for loss made by the player.
assistsInt64Assisted tackles.
grades_pass_rush_defenseFloat64PFF pass-rush grade, 0-100.
player_idInt64PFF player id (integer join key) of the player the report is about.
snap_counts_fsInt64Snaps aligned at free safety.
touchdownsInt64Touchdowns allowed into the player's coverage.
snap_counts_dl_outside_tInt64Defensive-line snaps aligned outside the offensive tackle.
game_away_franchise_idInt64Repeats away_franchise_id from the row's nested game object: PFF franchise id of the away team.
game_away_team_nameStringRepeats away_team_name from the row's nested game object: Abbreviation of the away team (e.g. "LV").
game_game_idInt64Repeats game_id from the row's nested game object: PFF game id of the game (integer join key).
game_home_franchise_idInt64Repeats home_franchise_id from the row's nested game object: PFF franchise id of the home team.
game_home_team_nameStringRepeats home_team_name from the row's nested game object: Abbreviation of the home team (e.g. "NE").
game_player_franchise_idInt64Repeats player_franchise_id from the row's nested game object: PFF franchise id of the team the player played for in the game.
game_positionStringRepeats position from the row's nested game object: PFF position code the player was charted at in the game (e.g. QB, HB, WR, T, LB, K).
game_statusStringRepeats status from the row's nested game object: "S" when the player started the game; PFF owns the value set.
game_weekInt64Repeats week from the row's nested game object: Week number of the game, as PFF numbers weeks.
league_idInt64PFF league id (1 = NFL, 2 = NCAA), filled from the report's subject.
seasonInt64Season (starting year) of the report, filled from the report's subject.

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_player_defense_summary(league='nfl', player_id=28022, season=2022)

pff_api_player_field_goal_summary​

Field-goal kicking for one player

Endpoint URL: GET https://api.pff.com/v1/player/field_goal/summary

Valid URL: https://api.pff.com/v1/player/field_goal/summary?league=nfl&season=2022&player_id=28022

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.
weekweekYWeek filter.
player_idplayer_idYPlayer id, taken as a positional argument.
careercareerYCareer-aggregate toggle, on the player report operations 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
twenty_attemptsInt64Field goals attempted from 20-29 yards.
game_idInt64PFF game id of the game (integer join key).
pat_percentFloat64Extra-point percentage.
weekInt64Week number of the game, as PFF numbers weeks.
statusString"S" when the player started the game; PFF owns the value set.
forty_madeInt64Field goals made from 40-49 yards.
fifty_percentFloat64Field-goal percentage from 50 or more yards.
total_madeInt64Total field goals made across all distances.
jersey_numberStringJersey number the player wore in the game (string; zero-padded, e.g. "09").
away_team_nameStringAbbreviation of the away team (e.g. "LV").
one_madeInt64Field goals made from 1-19 yards.
fifty_attemptsInt64Field goals attempted from 50 or more yards.
forty_attemptsInt64Field goals attempted from 40-49 yards.
thirty_percentFloat64Field-goal percentage from 30-39 yards.
total_attemptsInt64Total field goals attempted across all distances.
pat_attemptsInt64Extra points attempted.
player_franchise_idInt64PFF franchise id of the team the player played for in the game.
twenty_madeInt64Field goals made from 20-29 yards.
one_attemptsInt64Field goals attempted from 1-19 yards.
grades_fgep_kickerFloat64PFF field-goal and extra-point kicking grade, 0-100.
thirty_attemptsInt64Field goals attempted from 30-39 yards.
pat_madeInt64Extra points made.
one_percentFloat64Field-goal percentage from 1-19 yards.
total_percentFloat64Overall field-goal percentage.
positionStringPFF position code the player was charted at in the game (e.g. QB, HB, WR, T, LB, K).
twenty_percentFloat64Field-goal percentage from 20-29 yards.
away_franchise_idInt64PFF franchise id of the away team.
forty_percentFloat64Field-goal percentage from 40-49 yards.
fifty_madeInt64Field goals made from 50 or more yards.
thirty_madeInt64Field goals made from 30-39 yards.
home_franchise_idInt64PFF franchise id of the home team.
home_team_nameStringAbbreviation of the home team (e.g. "NE").
player_idInt64PFF player id (integer join key) of the player the report is about.
game_away_franchise_idInt64Repeats away_franchise_id from the row's nested game object: PFF franchise id of the away team.
game_away_team_nameStringRepeats away_team_name from the row's nested game object: Abbreviation of the away team (e.g. "LV").
game_game_idInt64Repeats game_id from the row's nested game object: PFF game id of the game (integer join key).
game_home_franchise_idInt64Repeats home_franchise_id from the row's nested game object: PFF franchise id of the home team.
game_home_team_nameStringRepeats home_team_name from the row's nested game object: Abbreviation of the home team (e.g. "NE").
game_player_franchise_idInt64Repeats player_franchise_id from the row's nested game object: PFF franchise id of the team the player played for in the game.
game_positionStringRepeats position from the row's nested game object: PFF position code the player was charted at in the game (e.g. QB, HB, WR, T, LB, K).
game_statusStringRepeats status from the row's nested game object: "S" when the player started the game; PFF owns the value set.
game_weekInt64Repeats week from the row's nested game object: Week number of the game, as PFF numbers weeks.
league_idInt64PFF league id (1 = NFL, 2 = NCAA), filled from the report's subject.
seasonInt64Season (starting year) of the report, filled from the report's subject.

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_player_field_goal_summary(league='nfl', player_id=28022, season=2022)

pff_api_player_kickoff_summary​

Kickoffs for one player

Endpoint URL: GET https://api.pff.com/v1/player/kickoff/summary

Valid URL: https://api.pff.com/v1/player/kickoff/summary?league=nfl&season=2022&player_id=28022

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.
weekweekYWeek filter.
player_idplayer_idYPlayer id, taken as a positional argument.
careercareerYCareer-aggregate toggle, on the player report operations 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
attemptsInt64Kickoffs by the player.
attempts_with_hangtimeInt64Kickoffs with a PFF-recorded hangtime.
average_distanceFloat64Average kickoff distance in yards.
average_hangtimeFloat64Average kickoff hangtime in seconds.
average_starting_field_positionFloat64Average opponent starting field position following the player's kickoffs.
average_yards_per_returnFloat64Average return yards allowed per kickoff returned.
away_franchise_idInt64PFF franchise id of the away team.
away_team_nameStringAbbreviation of the away team (e.g. "LV").
fair_catchesInt64Kickoffs fair-caught by the return team.
game_idInt64PFF game id of the game (integer join key).
grades_kickoff_kickerFloat64PFF kickoff kicking grade, 0-100.
home_franchise_idInt64PFF franchise id of the home team.
home_team_nameStringAbbreviation of the home team (e.g. "NE").
jersey_numberStringJersey number the player wore in the game (string; zero-padded, e.g. "09").
kicked_yardsInt64Total kickoff yards.
kicks_returnedInt64Kickoffs returned by the opponent.
onside_kicksInt64Onside kicks attempted.
percent_returnedFloat64Percentage of the player's kickoffs that were returned.
player_franchise_idInt64PFF franchise id of the team the player played for in the game.
player_idInt64PFF player id (integer join key) of the player the report is about.
positionStringPFF position code the player was charted at in the game (e.g. QB, HB, WR, T, LB, K).
return_yardsInt64Return yards gained by the return team on the player's kickoffs.
statusString"S" when the player started the game; PFF owns the value set.
total_hangtimeFloat64Total kickoff hangtime in seconds.
touchbacksInt64Kickoffs resulting in touchbacks.
weekInt64Week number of the game, as PFF numbers weeks.
game_away_franchise_idInt64Repeats away_franchise_id from the row's nested game object: PFF franchise id of the away team.
game_away_team_nameStringRepeats away_team_name from the row's nested game object: Abbreviation of the away team (e.g. "LV").
game_game_idInt64Repeats game_id from the row's nested game object: PFF game id of the game (integer join key).
game_home_franchise_idInt64Repeats home_franchise_id from the row's nested game object: PFF franchise id of the home team.
game_home_team_nameStringRepeats home_team_name from the row's nested game object: Abbreviation of the home team (e.g. "NE").
game_player_franchise_idInt64Repeats player_franchise_id from the row's nested game object: PFF franchise id of the team the player played for in the game.
game_positionStringRepeats position from the row's nested game object: PFF position code the player was charted at in the game (e.g. QB, HB, WR, T, LB, K).
game_statusStringRepeats status from the row's nested game object: "S" when the player started the game; PFF owns the value set.
game_weekInt64Repeats week from the row's nested game object: Week number of the game, as PFF numbers weeks.
league_idInt64PFF league id (1 = NFL, 2 = NCAA), filled from the report's subject.
seasonInt64Season (starting year) of the report, filled from the report's subject.

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_player_kickoff_summary(league='nfl', player_id=28022, season=2022)

pff_api_player_punting_summary​

Punting for one player

Endpoint URL: GET https://api.pff.com/v1/player/punting/summary

Valid URL: https://api.pff.com/v1/player/punting/summary?league=nfl&season=2022&player_id=28022

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.
weekweekYWeek filter.
player_idplayer_idYPlayer id, taken as a positional argument.
careercareerYCareer-aggregate toggle, on the player report operations 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
game_idInt64PFF game id of the game (integer join key).
touchbacksInt64Punts resulting in touchbacks.
attempts_with_hangtimeInt64Punts with a PFF-recorded hangtime.
percent_returnedFloat64Percentage of the player's punts that were returned.
weekInt64Week number of the game, as PFF numbers weeks.
statusString"S" when the player started the game; PFF owns the value set.
fair_catchesInt64Punts fair-caught by the return team.
jersey_numberStringJersey number the player wore in the game (string; zero-padded, e.g. "09").
away_team_nameStringAbbreviation of the away team (e.g. "LV").
average_net_yardsFloat64Average net punting yards per attempt.
yardsInt64Gross punt yards: the summed distance of the player's punts, before any return.
player_franchise_idInt64PFF franchise id of the team the player played for in the game.
average_hangtimeFloat64Average punt hangtime in seconds.
total_net_yardsInt64Total net punting yards.
attemptsInt64Punts by the player.
inside_twentiesInt64Punts downed inside the opponent 20-yard line.
out_of_boundsInt64Punts that went out of bounds.
average_yards_per_returnFloat64Average return yards allowed per punt returned.
total_hangtimeFloat64Total punt hangtime in seconds.
returnsInt64Punts returned by the opponent.
positionStringPFF position code the player was charted at in the game (e.g. QB, HB, WR, T, LB, K).
longInt64Longest punt in yards.
away_franchise_idInt64PFF franchise id of the away team.
blocksInt64Punts that were blocked.
average_yards_per_attemptFloat64Average gross punting yards per attempt.
grades_punterFloat64PFF punting grade, 0-100.
home_franchise_idInt64PFF franchise id of the home team.
home_team_nameStringAbbreviation of the home team (e.g. "NE").
return_yardsInt64Return yards gained by the return team on the player's punts.
downedsInt64Punts downed by the coverage unit.
player_idInt64PFF player id (integer join key) of the player the report is about.
snapsInt64Punting snaps played.
game_away_franchise_idInt64Repeats away_franchise_id from the row's nested game object: PFF franchise id of the away team.
game_away_team_nameStringRepeats away_team_name from the row's nested game object: Abbreviation of the away team (e.g. "LV").
game_game_idInt64Repeats game_id from the row's nested game object: PFF game id of the game (integer join key).
game_home_franchise_idInt64Repeats home_franchise_id from the row's nested game object: PFF franchise id of the home team.
game_home_team_nameStringRepeats home_team_name from the row's nested game object: Abbreviation of the home team (e.g. "NE").
game_player_franchise_idInt64Repeats player_franchise_id from the row's nested game object: PFF franchise id of the team the player played for in the game.
game_positionStringRepeats position from the row's nested game object: PFF position code the player was charted at in the game (e.g. QB, HB, WR, T, LB, K).
game_statusStringRepeats status from the row's nested game object: "S" when the player started the game; PFF owns the value set.
game_weekInt64Repeats week from the row's nested game object: Week number of the game, as PFF numbers weeks.
league_idInt64PFF league id (1 = NFL, 2 = NCAA), filled from the report's subject.
seasonInt64Season (starting year) of the report, filled from the report's subject.

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_player_punting_summary(league='nfl', player_id=28022, season=2022)

pff_api_player_return_summary​

Kick and punt returns for one player

Endpoint URL: GET https://api.pff.com/v1/player/return/summary

Valid URL: https://api.pff.com/v1/player/return/summary?league=nfl&season=2022&player_id=28022

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.
weekweekYWeek filter.
player_idplayer_idYPlayer id, taken as a positional argument.
careercareerYCareer-aggregate toggle, on the player report operations 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
away_franchise_idInt64PFF franchise id of the away team.
away_team_nameStringAbbreviation of the away team (e.g. "LV").
game_idInt64PFF game id of the game (integer join key).
grades_punt_returnFloat64PFF punt-return grade, 0-100.
grades_returnFloat64PFF overall return grade, 0-100.
home_franchise_idInt64PFF franchise id of the home team.
home_team_nameStringAbbreviation of the home team (e.g. "NE").
jersey_numberStringJersey number the player wore in the game (string; zero-padded, e.g. "09").
kickoff_attemptsInt64Kickoff returns attempted.
kickoff_count_of_yardsInt64Kickoff returns counted toward the return-yardage figures (equal to kickoff_attempts in the captured rows).
kickoff_fair_catchesInt64Kickoffs fair-caught by the player.
kickoff_longInt64Longest kickoff return in yards.
kickoff_muffed_returnsInt64Kickoff returns the player muffed.
kickoff_touchdownsInt64Kickoff returns scoring a touchdown.
kickoff_yardsInt64Total kickoff-return yards.
kickoff_ypaFloat64Average yards per kickoff return.
player_franchise_idInt64PFF franchise id of the team the player played for in the game.
player_idInt64PFF player id (integer join key) of the player the report is about.
positionStringPFF position code the player was charted at in the game (e.g. QB, HB, WR, T, LB, K).
punt_attemptsInt64Punt returns attempted.
punt_count_of_yardsInt64Punt returns counted toward the return-yardage figures (equal to punt_attempts in the captured rows).
punt_fair_catchesInt64Punts fair-caught by the player.
punt_longInt64Longest punt return in yards.
punt_muffed_returnsInt64Punt returns the player muffed.
punt_touchdownsInt64Punt returns scoring a touchdown.
punt_yardsInt64Total punt-return yards.
punt_ypaFloat64Average yards per punt return.
statusString"S" when the player started the game; PFF owns the value set.
total_attemptsInt64Total return attempts, kickoffs and punts combined.
weekInt64Week number of the game, as PFF numbers weeks.
game_away_franchise_idInt64Repeats away_franchise_id from the row's nested game object: PFF franchise id of the away team.
game_away_team_nameStringRepeats away_team_name from the row's nested game object: Abbreviation of the away team (e.g. "LV").
game_game_idInt64Repeats game_id from the row's nested game object: PFF game id of the game (integer join key).
game_home_franchise_idInt64Repeats home_franchise_id from the row's nested game object: PFF franchise id of the home team.
game_home_team_nameStringRepeats home_team_name from the row's nested game object: Abbreviation of the home team (e.g. "NE").
game_player_franchise_idInt64Repeats player_franchise_id from the row's nested game object: PFF franchise id of the team the player played for in the game.
game_positionStringRepeats position from the row's nested game object: PFF position code the player was charted at in the game (e.g. QB, HB, WR, T, LB, K).
game_statusStringRepeats status from the row's nested game object: "S" when the player started the game; PFF owns the value set.
game_weekInt64Repeats week from the row's nested game object: Week number of the game, as PFF numbers weeks.
league_idInt64PFF league id (1 = NFL, 2 = NCAA), filled from the report's subject.
seasonInt64Season (starting year) of the report, filled from the report's subject.
grades_kick_returnFloat64PFF kickoff-return grade, 0-100.

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_player_return_summary(league='nfl', player_id=28022, season=2022)

pff_api_player_special_summary​

Special-teams summary for one player

Endpoint URL: GET https://api.pff.com/v1/player/special/summary

Valid URL: https://api.pff.com/v1/player/special/summary?league=nfl&season=2022&player_id=28022

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.
weekweekYWeek filter.
player_idplayer_idYPlayer id, taken as a positional argument.
careercareerYCareer-aggregate toggle, on the player report operations 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
assistsInt64Assisted tackles credited to the player on special-teams plays.
away_franchise_idInt64PFF franchise id of the away team.
away_team_nameStringAbbreviation of the away team (e.g. "LV").
declined_penaltiesInt64Penalties committed by the player that were declined.
game_idInt64PFF game id of the game (integer join key).
grades_fgep_defenseFloat64PFF grade on field-goal and extra-point defense, 0-100.
grades_misc_stFloat64PFF miscellaneous special-teams grade, 0-100.
grades_special_teams_penaltyFloat64PFF special-teams penalty grade, 0-100.
home_franchise_idInt64PFF franchise id of the home team.
home_team_nameStringAbbreviation of the home team (e.g. "NE").
jersey_numberStringJersey number the player wore in the game (string; zero-padded, e.g. "09").
missed_tacklesInt64Missed tackles on special-teams plays.
penaltiesInt64Penalties charged to the player over the covered span.
player_franchise_idInt64PFF franchise id of the team the player played for in the game.
player_idInt64PFF player id (integer join key) of the player the report is about.
positionStringPFF position code the player was charted at in the game (e.g. QB, HB, WR, T, LB, K).
pu_def_rushInt64PFF punt-defense rush count (PFF's pu_def_rush; PFF does not document it further).
snap_counts_field_goalInt64Snaps on the field-goal and extra-point unit.
snap_counts_field_goal_blockingInt64Snaps on the field-goal and extra-point block unit.
snap_counts_kickoffInt64Snaps on the kickoff coverage unit.
snap_counts_kickoff_returnInt64Snaps on the kickoff return unit.
snap_counts_punt_coverageInt64Snaps on the punt coverage unit.
snap_counts_punt_returnInt64Snaps on the punt return unit.
statusString"S" when the player started the game; PFF owns the value set.
tacklesInt64Tackles made by the player on special-teams plays.
weekInt64Week number of the game, as PFF numbers weeks.
game_away_franchise_idInt64Repeats away_franchise_id from the row's nested game object: PFF franchise id of the away team.
game_away_team_nameStringRepeats away_team_name from the row's nested game object: Abbreviation of the away team (e.g. "LV").
game_game_idInt64Repeats game_id from the row's nested game object: PFF game id of the game (integer join key).
game_home_franchise_idInt64Repeats home_franchise_id from the row's nested game object: PFF franchise id of the home team.
game_home_team_nameStringRepeats home_team_name from the row's nested game object: Abbreviation of the home team (e.g. "NE").
game_player_franchise_idInt64Repeats player_franchise_id from the row's nested game object: PFF franchise id of the team the player played for in the game.
game_positionStringRepeats position from the row's nested game object: PFF position code the player was charted at in the game (e.g. QB, HB, WR, T, LB, K).
game_statusStringRepeats status from the row's nested game object: "S" when the player started the game; PFF owns the value set.
game_weekInt64Repeats week from the row's nested game object: Week number of the game, as PFF numbers weeks.
league_idInt64PFF league id (1 = NFL, 2 = NCAA), filled from the report's subject.
seasonInt64Season (starting year) of the report, filled from the report's subject.

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_player_special_summary(league='nfl', player_id=28022, season=2022)