Skip to main content

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

pff_api_facet_field_goal_summary​

League-wide field-goal kicking leaderboard

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

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

API ParameterPythonPatternRequiredNullableDescription
leagueleagueYLeague slug for the leaderboard commands — exactly nfl, ncaa, hs, aaf and ufl are recognised; anything else is rejected.
seasonseasonYSeason for the leaderboard commands.
weekweekYWeek filter.
franchise_idfranchise_idYFranchise (team) id.
game_idgame_idYSingle-game filter, facet family only, forwarded uncoerced.
divisiondivisionYNCAA division fan-out, facet family only, and only honoured when league=ncaa — for any other league it is ignored entirely.

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_attemptsFloat64Field goals attempted from 20-29 yards.
pat_percentFloat64Extra-point percentage.
draft_seasonFloat64Season of the player's NFL draft class, per PFF.
forty_madeFloat64Field goals made from 40-49 yards.
team_nameStringTeam abbreviation the player is credited to for the range.
fifty_percentFloat64Field-goal percentage from 50 or more yards.
total_madeFloat64Total field goals made across all distances.
jersey_numberStringJersey number (string; zero-padded, e.g. "09").
one_madeFloat64Field goals made from 1-19 yards.
fifty_attemptsFloat64Field goals attempted from 50 or more yards.
forty_attemptsFloat64Field goals attempted from 40-49 yards.
player_game_countFloat64Number of games the player appeared in over the covered span.
eligible_seasonFloat64Season of the player's NFL draft eligibility, per PFF.
thirty_percentFloat64Field-goal percentage from 30-39 yards.
total_attemptsFloat64Total field goals attempted across all distances.
pat_attemptsFloat64Extra points attempted.
twenty_madeFloat64Field goals made from 20-29 yards.
one_attemptsFloat64Field goals attempted from 1-19 yards.
grades_fgep_kickerFloat64PFF field-goal and extra-point kicking grade, 0-100.
thirty_attemptsFloat64Field goals attempted from 30-39 yards.
penaltiesFloat64Penalties charged to the player over the covered span.
pat_madeFloat64Extra points made.
teamStringTeam abbreviation the player is credited to for the range.
declined_penaltiesFloat64Penalties committed by the player that were declined.
one_percentFloat64Field-goal percentage from 1-19 yards.
total_percentFloat64Overall field-goal percentage.
positionStringPFF position code the player is listed at (e.g. QB, HB, FB, WR, TE, T, G, C, ED, DI, LB, CB, S, K, P).
twenty_percentFloat64Field-goal percentage from 20-29 yards.
forty_percentFloat64Field-goal percentage from 40-49 yards.
playerStringPlayer's display name as PFF lists it.
franchise_idFloat64PFF franchise (team) id (integer join key).
fifty_madeFloat64Field goals made from 50 or more yards.
thirty_madeFloat64Field goals made from 30-39 yards.
player_idFloat64PFF player id (integer; matches the /players id and every player_id join key).

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

pff_api_facet_kickoff_summary​

League-wide kickoff leaderboard

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

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

API ParameterPythonPatternRequiredNullableDescription
leagueleagueYLeague slug for the leaderboard commands — exactly nfl, ncaa, hs, aaf and ufl are recognised; anything else is rejected.
seasonseasonYSeason for the leaderboard commands.
weekweekYWeek filter.
franchise_idfranchise_idYFranchise (team) id.
game_idgame_idYSingle-game filter, facet family only, forwarded uncoerced.
divisiondivisionYNCAA division fan-out, facet family only, and only honoured when league=ncaa — for any other league it is ignored entirely.

Returns​

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

col_nametypedescription
attemptsFloat64Kickoffs by the player.
attempts_with_hangtimeFloat64Kickoffs 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.
declined_penaltiesFloat64Penalties committed by the player that were declined.
draft_seasonFloat64Season of the player's NFL draft class, per PFF.
eligible_seasonFloat64Season of the player's NFL draft eligibility, per PFF.
fair_catchesFloat64Kickoffs fair-caught by the return team.
franchise_idFloat64PFF franchise (team) id (integer join key).
grades_kickoff_kickerFloat64PFF kickoff kicking grade, 0-100.
jersey_numberStringJersey number (string; zero-padded, e.g. "09").
kicked_yardsFloat64Total kickoff yards.
kicks_returnedFloat64Kickoffs returned by the opponent.
onside_kicksFloat64Onside kicks attempted.
penaltiesFloat64Penalties charged to the player over the covered span.
percent_returnedFloat64Percentage of the player's kickoffs that were returned.
playerStringPlayer's display name as PFF lists it.
player_game_countFloat64Number of games the player appeared in over the covered span.
player_idFloat64PFF player id (integer; matches the /players id and every player_id join key).
positionStringPFF position code the player is listed at (e.g. QB, HB, FB, WR, TE, T, G, C, ED, DI, LB, CB, S, K, P).
return_yardsFloat64Return yards gained by the return team on the player's kickoffs.
teamStringTeam abbreviation the player is credited to for the range.
team_nameStringTeam abbreviation the player is credited to for the range.
total_hangtimeFloat64Total kickoff hangtime in seconds.
touchbacksFloat64Kickoffs resulting in touchbacks.

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

pff_api_facet_punting_summary​

League-wide punting leaderboard

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

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

API ParameterPythonPatternRequiredNullableDescription
leagueleagueYLeague slug for the leaderboard commands — exactly nfl, ncaa, hs, aaf and ufl are recognised; anything else is rejected.
seasonseasonYSeason for the leaderboard commands.
weekweekYWeek filter.
franchise_idfranchise_idYFranchise (team) id.
game_idgame_idYSingle-game filter, facet family only, forwarded uncoerced.
divisiondivisionYNCAA division fan-out, facet family only, and only honoured when league=ncaa — for any other league it is ignored entirely.

Returns​

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

col_nametypedescription
touchbacksFloat64Punts resulting in touchbacks.
attempts_with_hangtimeFloat64Punts with a PFF-recorded hangtime.
draft_seasonFloat64Season of the player's NFL draft class, per PFF.
percent_returnedFloat64Percentage of the player's punts that were returned.
fair_catchesFloat64Punts fair-caught by the return team.
team_nameStringTeam abbreviation the player is credited to for the range.
jersey_numberStringJersey number (string; zero-padded, e.g. "09").
player_game_countFloat64Number of games the player appeared in over the covered span.
eligible_seasonFloat64Season of the player's NFL draft eligibility, per PFF.
average_net_yardsFloat64Average net punting yards per attempt.
yardsFloat64Gross punt yards: the summed distance of the player's punts, before any return.
average_hangtimeFloat64Average punt hangtime in seconds.
total_net_yardsFloat64Total net punting yards.
penaltiesFloat64Penalties charged to the player over the covered span.
attemptsFloat64Punts by the player.
inside_twentiesFloat64Punts downed inside the opponent 20-yard line.
out_of_boundsFloat64Punts that went out of bounds.
teamStringTeam abbreviation the player is credited to for the range.
average_yards_per_returnFloat64Average return yards allowed per punt returned.
total_hangtimeFloat64Total punt hangtime in seconds.
declined_penaltiesFloat64Penalties committed by the player that were declined.
returnsFloat64Punts returned by the opponent.
positionStringPFF position code the player is listed at (e.g. QB, HB, FB, WR, TE, T, G, C, ED, DI, LB, CB, S, K, P).
longFloat64Longest punt in yards.
blocksFloat64Punts that were blocked.
average_yards_per_attemptFloat64Average gross punting yards per attempt.
playerStringPlayer's display name as PFF lists it.
franchise_idFloat64PFF franchise (team) id (integer join key).
grades_punterFloat64PFF punting grade, 0-100.
return_yardsFloat64Return yards gained by the return team on the player's punts.
downedsFloat64Punts downed by the coverage unit.
player_idFloat64PFF player id (integer; matches the /players id and every player_id join key).
snapsFloat64Punting snaps played.

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

pff_api_facet_return_summary​

League-wide return leaderboard

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

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

API ParameterPythonPatternRequiredNullableDescription
leagueleagueYLeague slug for the leaderboard commands — exactly nfl, ncaa, hs, aaf and ufl are recognised; anything else is rejected.
seasonseasonYSeason for the leaderboard commands.
weekweekYWeek filter.
franchise_idfranchise_idYFranchise (team) id.
game_idgame_idYSingle-game filter, facet family only, forwarded uncoerced.
divisiondivisionYNCAA division fan-out, facet family only, and only honoured when league=ncaa — for any other league it is ignored entirely.

Returns​

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

col_nametypedescription
declined_penaltiesFloat64Penalties committed by the player that were declined.
draft_seasonFloat64Season of the player's NFL draft class, per PFF.
eligible_seasonFloat64Season of the player's NFL draft eligibility, per PFF.
franchise_idFloat64PFF franchise (team) id (integer join key).
grades_kick_returnFloat64PFF kickoff-return grade, 0-100.
grades_returnFloat64PFF overall return grade, 0-100.
jersey_numberStringJersey number (string; zero-padded, e.g. "09").
kickoff_attemptsFloat64Kickoff returns attempted.
kickoff_fair_catchesFloat64Kickoffs fair-caught by the player.
kickoff_longFloat64Longest kickoff return in yards.
kickoff_muffed_returnsFloat64Kickoff returns the player muffed.
kickoff_touchdownsFloat64Kickoff returns scoring a touchdown.
kickoff_yardsFloat64Total kickoff-return yards.
kickoff_ypaFloat64Average yards per kickoff return.
penaltiesFloat64Penalties charged to the player over the covered span.
playerStringPlayer's display name as PFF lists it.
player_game_countFloat64Number of games the player appeared in over the covered span.
player_idFloat64PFF player id (integer; matches the /players id and every player_id join key).
positionStringPFF position code the player is listed at (e.g. QB, HB, FB, WR, TE, T, G, C, ED, DI, LB, CB, S, K, P).
punt_attemptsFloat64Punt returns attempted.
punt_fair_catchesFloat64Punts fair-caught by the player.
punt_longFloat64Longest punt return in yards.
punt_muffed_returnsFloat64Punt returns the player muffed.
punt_touchdownsFloat64Punt returns scoring a touchdown.
punt_yardsFloat64Total punt-return yards.
punt_ypaFloat64Average yards per punt return.
teamStringTeam abbreviation the player is credited to for the range.
team_nameStringTeam abbreviation the player is credited to for the range.
total_attemptsFloat64Total return attempts, kickoffs and punts combined.
grades_punt_returnFloat64PFF punt-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_facet_return_summary(league='nfl', season='2022')

pff_api_facet_special_summary​

League-wide special-teams leaderboard

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

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

API ParameterPythonPatternRequiredNullableDescription
leagueleagueYLeague slug for the leaderboard commands — exactly nfl, ncaa, hs, aaf and ufl are recognised; anything else is rejected.
seasonseasonYSeason for the leaderboard commands.
weekweekYWeek filter.
franchise_idfranchise_idYFranchise (team) id.
game_idgame_idYSingle-game filter, facet family only, forwarded uncoerced.
divisiondivisionYNCAA division fan-out, facet family only, and only honoured when league=ncaa — for any other league it is ignored entirely.

Returns​

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

col_nametypedescription
assistsFloat64Assisted tackles credited to the player on special-teams plays.
declined_penaltiesFloat64Penalties committed by the player that were declined.
draft_seasonFloat64Season of the player's NFL draft class, per PFF.
eligible_seasonFloat64Season of the player's NFL draft eligibility, per PFF.
franchise_idFloat64PFF franchise (team) id (integer join key).
grades_fgep_kickerFloat64PFF field-goal and extra-point kicking grade, 0-100.
grades_kickoff_kickerFloat64PFF kickoff kicking grade, 0-100.
grades_misc_stFloat64PFF miscellaneous special-teams grade, 0-100.
grades_special_teams_penaltyFloat64PFF special-teams penalty grade, 0-100.
jersey_numberStringJersey number (string; zero-padded, e.g. "09").
missed_tacklesFloat64Missed tackles on special-teams plays.
penaltiesFloat64Penalties charged to the player over the covered span.
playerStringPlayer's display name as PFF lists it.
player_game_countFloat64Number of games the player appeared in over the covered span.
player_idFloat64PFF player id (integer; matches the /players id and every player_id join key).
positionStringPFF position code the player is listed at (e.g. QB, HB, FB, WR, TE, T, G, C, ED, DI, LB, CB, S, K, P).
snap_counts_field_goalFloat64Snaps on the field-goal and extra-point unit.
snap_counts_field_goal_blockingFloat64Snaps on the field-goal and extra-point block unit.
snap_counts_kickoffFloat64Snaps on the kickoff coverage unit.
snap_counts_kickoff_returnFloat64Snaps on the kickoff return unit.
snap_counts_punt_coverageFloat64Snaps on the punt coverage unit.
snap_counts_punt_returnFloat64Snaps on the punt return unit.
tacklesFloat64Tackles made by the player on special-teams plays.
teamStringTeam abbreviation the player is credited to for the range.
team_nameStringTeam abbreviation the player is credited to for the range.
grades_fgep_defenseFloat64PFF grade on field-goal and extra-point defense, 0-100.
grades_fgep_offenseFloat64PFF grade on the field-goal and extra-point protection unit, 0-100.
grades_long_snapFloat64PFF long-snapping grade, 0-100.
grades_punterFloat64PFF punting grade, 0-100.
grades_kick_returnFloat64PFF kickoff-return grade, 0-100.
grades_punt_returnFloat64PFF punt-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_facet_special_summary(league='nfl', season='2022')