Skip to contents

nflreadr (development version)


  • %c% internal helper now uses data.table::fifelse() to avoid falsely converting dates to integers. (#214)
  • load_schedules() cleans the roof variable in order to avoid nflverse model issues. (#218)
  • join_coalesce() coerces x/y args to data.frame and will return a data.frame
  • most_recent_season() now internally computes the exact day of the season opener (= Thursday after first Monday of September). (#221)
  • Internal changes to load_espn_qbr() to align with nflverse infrastructure design. Also dropped the argument “league” which used to allow loading of College QBR. That’s outside of the nflverse scope. (#222)
  • Add new function stat_mode(), a re-export from nflfastR, which computes the statistical mode of a vector. (#224)
  • The function load_ftn_charting() now accepts the argument file_type. (#228)
  • The function clean_team_abbrs() now accepts the “team” name “NFL”. (#231)
  • load_participation() now returns additional fields time_to_throw, was_pressure, defense_man_zone_type, and defense_coverage_type (#233, thank you @mistakia @john-b-edwards)
  • clean_player_names() now can transliterate to latin-ascii if the stringi package is available, controlled by the convert_to_ascii argument.

nflreadr 1.4.0

CRAN release: 2023-09-05

This release addresses bugs, improves some utilities, and adds a few new datasets.

New Datasets

  • load_player_stats(stat_type = "defense") added to provide defensive player stats as computed by nflfastR::calculate_player_stats_def() (#200) It also comes with a data dictionary, courtesy of @mpcen (#192)
  • load_ftn_charting() adds manual charting data for 2022-onwards, graciously provided by FTN Data. This should automatically be updated when published by FTN, and the early indication is that it will be within 48 hours after a game has finished.

Function Improvements

  • nflverse_sitrep() and friends overhauled:
    • now returns a list of sitrep attributes rather than only printing to console (for programmatic use)
    • now checks CRAN and r-universe to tell you if your installation is behind cran or devel
    • now handles dependencies for nflverse/ffverse packages that are not on CRAN
  • nflreadr::most_recent_season() and aliases get_latest_season, get_current_season etc now use March 15th as the changeover for league year. Hopefully this is not a moving target 🙃
  • nflreadr::clean_homeaway() now handles columns with suffixes _home and _away
  • nflreadr::nflverse_game_id() now accepts old team abbreviations and outputs useful errors.
  • Added .for_cran() to limit parallelization in CRAN examples and tests
  • make_nflverse_data_class() now uses data.table::setattr() to preserve data.table pointer

Dictionary updates

  • Clarified description of the "special" variable in the play-by-play data dictionary. (#189)

Thank you to @ak47twq, @alecglen, @andycancapital, @bullaspc, @mcarman8, @mpcen, @mrcaseb, @tanho63, @tashapiro, and @TheMathNinja for their questions, feedback, and contributions to this release

nflreadr 1.3.2

CRAN release: 2023-01-06

Minor changes per changelist and patch CRAN-related example issue.


Thank you to @ak47twq, @bachlaw, @brunomioto, @guga31bb, @Josephhero, @kharigardner, @mrcaseb, @MysteryPollster, @numbersinfigures, and @ohri for their questions, feedback, and contributions towards this release.

nflreadr 1.3.1

CRAN release: 2022-09-25

Fixes CRAN bug and provides some function improvements, most notably improved logic for load_participation()’s pbp join.

New Features

  • Added nflverse_game_id() which computes valid nflverse game identifiers in the format "{season}_{week}_{away}_{home}"

Function Updates

  • load_participation() now joins pbp on via nflverse_game_id instead of old_game_id
  • load_snap_counts() now allows download of the 2012 season which was previously hardcoded from 2013 (#128)
  • progressively() now works with purrr-style lambda functions and no longer checks for progressor class, allowing it to be used more flexibly (and with cli-based progress bars.)


Thank you to @atungate, @grayhawk40, @guga31bb,@jestarr, @john-b-edwards,@marvin3FF,@mrcaseb, @SCasanova, @shirondru, @tanho63, and @TheMathNinja for their contributions and feedback towards this release!

nflreadr 1.3.0

CRAN release: 2022-08-06

This release introduces several new data functions, some new utilities, and an array of data/function updates.

New Data!

  • load_participation() returns new play-level information about what players are on the field, how many players are in the box, and what formation the offense is using. Data from NGS starting 2016 and onward
  • load_contracts() downloads (historical) player contracts from
  • load_players() returns player-level information and is the new recommended source (over rosters) for IDs, positions, birthdates etc.
  • load_rosters_weekly() provides week-by-week team rosters dating back to 2002.
  • load_officials() returns game-level information about which officials are assigned to specific games.

New Functions!

Function Updates!

  • load_draft_picks() now has the rest of the career stat fields from PFR
  • *sitrep() functions now report package-specific options that are set.
  • get_current_week() helper to get the current nfl season week
  • load_rosters() now provides season-level rosters dating back to 1920.

Other bugfixes

  • moved rbindlist to a helper that manages attributes better
  • update dictionary_snap_counts and dictionary_schedules with some missing fields
  • rewrite from_url error messages to use cli and improve usefulness
  • bump minimum rlang version to 1.0.0
  • add piggyback suggested dependency
  • Export old class to support S4/DBI/nflfastR::update_db() as if it were a tibble
  • Fix exportOldClass so that it supports only data.frame stuff? we have no idea,,,
  • options(nflreadr.prefer) defaults to rds now since qs is no longer a required dependency
  • clean_player_names() now also removes commas (after optionally using them for convert_lastfirst)
  • clean_player_names() now also removes all caps suffixes
  • dictionary updates: return labelled.
  • .sitrep() exits nicely if no packages are to be investigated. #114
  • refactored all the loaders to use load_from_url as primary
  • fixed broken example in load_ff_opportunity() documentation. #117

Thank you to @albtree, @john-b-edwards, @mrcaseb, @pranavrajaram, @tanho63, and @tpenney89 for their contributions and feedback on this release!

nflreadr 1.2.0

CRAN release: 2022-03-17

This release updates all nflverse URLs to use the new nflverse-data repository releases, as well as provides improved pretty-printing methods that tell you when the data was last updated.

nflreadr 1.1.3

CRAN release: 2022-01-28

This release adds functions and arguments to access new data, along with some backend changes.

New data and functions


  • options(nflreadr.verbose) replaces options(nflreadr.cache_warning) as the best way to silence nflreadr messages.
  • Improved data dictionaries for ESPN QBR, Injuries, Trades, Depth Charts, and Combine
  • Exported most_recent_season() function
  • Updated documentation with improved linking and where to file data issues.
  • Sitrep functions have ffopportunity and nflverse packages.
  • Pkgdown site upgraded to Bootstrap 5.

Thank you to @armstjc, @Grayhawk34, @john-b-edwards, @mrcaseb, @pranavrajaram, @rogers1000, and @tanho63 for their contributions and feedback on this release!

nflreadr 1.1.2

CRAN release: 2021-12-08

New Functions

  • nflverse_sitrep() and ffverse_sitrep() give a minimal overview of the package dependencies
  • Minimum R version bumped to R 3.6.0 - this is the minimum version required to read the current RDS file-version.
  • _sitrep() functions receive a small print-related bugfix and colouring improvement.

nflreadr 1.1.1

CRAN release: 2021-10-05

New Data and Functions

  • clean_player_names() and clean_team_abbrs() added - these help standardise player names and team abbreviations based on internal dictionaries.
  • load_ff_rankings() now has a type argument and can return "draft" or "week" rankings from the DynastyProcess/data repo.
  • clean_homeaway() converts a dataframe of games with columns prefixed with home_ and away_ to a dataframe of teams, renaming to team_ and opponent_ and doubling the rows.
  • Added load_pfr_advstats() which provides pass, rush, rec, def additional data for each week.

Bug Fixes

  • Add Rcpp and RcppParallel minimum dependencies to fix qs issues.
  • Added a message that reminds the user of the caching behavior. The message will be displayed once every 8 hours if the session is interactive.
  • Adjusted file location of snap count data

Thank you to @ajreinhard, @brunomioto, @jthomasmock, @mrcaseb, @SCasanova, and @tanho63 for their feedback and contributions to this package!

nflreadr 1.1.0

CRAN release: 2021-09-02

This release makes some backend changes for speed, reduced dependency footprint, and ease of maintenance.

New Data

  • load_player_stats() can now retrieve weekly summaries of kicking data by specifying the stat_type argument to be "kicking".
  • load_combine() retrieves NFL combine data (from PFR).

Backend Changes

  • Remove progress handling from *_from_url() family of functions and move responsibility to progressively() function decorator instead. See vignette for details.
  • Removed dependency on dplyr and purrr in favour of data.table - this hopefully improves speed and reduces the dependency footprint.
  • Uses rlang::arg_match0 instead of match.arg (uses rlang explicitly instead of implicitly as a dependency of memoise).

nflreadr 1.0.0

CRAN release: 2021-08-09

The goal of {nflreadr} is to efficiently load data from nflverse GitHub repositories, and features caching, optional progress updates, and data dictionaries.

At this time, it includes data from the following repositories:

This will hopefully provide a unified and reliable package for downloading nflverse data that can be extended to the rest of the nflverse and ffverse package families.

Special thanks to Seb, Ben, John, Lee, and Thomas for their contributions to the package and to the data pipelines that this package relies on 🎉