fantasy-football

The fflr package helps easily access data from the ESPN fantasy football v3 API. Both current and historical data can be

Games

Some functions work independently of your specific league. As of now, this package only works with data from fantasy football leagues, but other fantasy sports exist.

espn_games()
#> # A tibble: 4 x 7
#>   game  active  year pro_league pro_sport  start_date          end_date           
#>   <chr> <lgl>  <int> <chr>      <chr>      <dttm>              <dttm>             
#> 1 FFL   TRUE    2020 NFL        football   2020-03-09 03:00:00 2022-03-09 02:00:00
#> 2 FLB   TRUE    2020 MLB        baseball   2020-01-22 03:00:00 2022-01-22 03:00:00
#> 3 FBA   TRUE    2020 NBA        basketball 2019-06-14 03:00:00 2021-06-14 03:00:00
#> 4 FHL   TRUE    2020 NHL        hockey     2019-07-19 03:00:00 2021-07-19 03:00:00

This package is designed to retrieve both current and historical data from the ESPN API. There are 17 years of seasons listed in the API!

ffl_seasons()
#> # A tibble: 17 x 6
#>    game   year  week pro_league start_date          end_date           
#>    <chr> <int> <int> <chr>      <dttm>              <dttm>             
#>  1 FFL    2020     8 NFL        2020-03-09 03:00:00 2022-03-09 02:00:00
#>  2 FFL    2019    18 NFL        2019-02-06 03:00:00 2020-03-09 03:00:00
#>  3 FFL    2018    18 NFL        2018-01-01 03:00:00 2019-02-06 03:00:00
#>  4 FFL    2017    18 NFL        2017-01-01 03:00:00 2019-01-01 03:00:00
#>  5 FFL    2016    18 NFL        2016-01-01 00:00:00 2018-01-01 00:00:00
#>  6 FFL    2015    18 NFL        2015-01-01 00:00:00 2015-12-31 23:59:59
#>  7 FFL    2014    18 NFL        2014-01-01 00:00:00 2014-12-31 23:59:59
#>  8 FFL    2013    18 NFL        2013-01-01 00:00:00 2013-12-31 23:59:59
#>  9 FFL    2012    18 NFL        2012-01-03 00:00:00 2012-12-31 23:59:59
#> 10 FFL    2011    18 NFL        2011-01-01 00:00:00 2012-01-03 00:00:00
#> 11 FFL    2010    18 NFL        2010-01-04 00:00:00 2011-01-01 00:00:00
#> 12 FFL    2009    18 NFL        2009-01-01 00:00:00 2010-01-04 00:00:00
#> 13 FFL    2008    18 NFL        2008-06-06 00:00:00 2009-01-01 00:00:00
#> 14 FFL    2007    18 NFL        2007-01-01 00:00:00 2008-06-06 00:00:00
#> 15 FFL    2006    18 NFL        2006-01-01 00:00:00 2007-01-01 00:00:00
#> 16 FFL    2005    18 NFL        2005-01-01 00:00:00 2006-01-01 00:00:00
#> 17 FFL    2004    18 NFL        2004-06-01 00:00:00 2005-01-01 00:00:00

The current season and scoring period are pieces of data that can be easily accessed and referenced for data manipulation.

str(ffl_info())
#> List of 6
#>  $ game      : chr "FFL"
#>  $ active    : logi TRUE
#>  $ year      : int 2020
#>  $ week      : int 8
#>  $ start_date: POSIXct[1:1], format: "2020-03-09 03:00:00"
#>  $ end_date  : POSIXct[1:1], format: "2022-03-09 02:00:00"

ffl_year()
#> [1] 2020
ffl_week()
#> [1] 8

To easily refer to past or future years and weeks, simply add an offset integer.

ffl_year(offset = -2)
#> [1] 2018
ffl_week(offset =  1)
#> [1] 9

Leagues

To access data on your league you will need to first use the league manager tools to make your league viewable to the public. This ESPN help page explains how this can be done; the option is found in the basic settings section of the fantasy football website.

Once your league is set to public, you’ll need to find the unique numeric league ID found in the URL of any page. This league ID (LID) is needed to access league specific information like rosters, scores, and transactions.

https://fantasy.espn.com/football/league?leagueId=252353

For convenience, the lid argument to most functions defaults to looking for an “lid” global option. Use options() to set your league ID and put the line in your ~/.Rprofile file to set at start up.

options(lid = 252353)

With our league ID option set, we can now easily retrieve league information.

str(league_info())
#> List of 6
#>  $ year  : int 2020
#>  $ name  : chr "Gambling Addicts Anonymous"
#>  $ id    : int 252353
#>  $ public: logi TRUE
#>  $ size  : int 8
#>  $ length: int 16

As we can see, my league this season has 8 teams and runs for 16 weeks.

Before we look into fantasy scores and player data, we’ll look a little more into how our league is set up.

We can identify the league members and the fantasy teams they own. Fantasy teams can have multiple owners, so team owners are identified by a nested list of unique member hashes.

league_members()
#> # A tibble: 8 x 4
#>    year user              owners                                 lm   
#>   <int> <chr>             <chr>                                  <lgl>
#> 1  2020 Angusg396         {12E61406-349A-4DC7-A614-06349AADC797} FALSE
#> 2  2020 k5cents_          {22DFE7FF-9DF2-4F3B-9FE7-FF9DF2AF3BD2} TRUE 
#> 3  2020 NAudet14          {35D9B7DB-E821-453C-99B7-DBE821353C36} FALSE
#> 4  2020 b.pepe            {5FA14794-6573-4189-A147-9465737189B2} FALSE
#> 5  2020 Billy.Slocum      {91F8B424-1689-472E-B8B4-241689172E35} FALSE
#> 6  2020 ESPNfan0199065799 {9A722A48-6E16-42BC-9E0E-AC9E4E6D7ABC} FALSE
#> 7  2020 espnfan1043876390 {C61F403A-F689-4269-879E-145B897F2308} FALSE
#> 8  2020 MrBruiser12       {F33F0723-2CC3-4A1C-BF07-232CC34A1C15} FALSE

League teams are occasionally only identified by their team number instead of their nickname or abbreviation. The data frame returned by league_teams() can be used to convert these team numbers.

(teams = league_teams())
#> # A tibble: 8 x 5
#>    year  team abbrev owners    name                    
#>   <int> <int> <fct>  <list>    <chr>                   
#> 1  2020     1 AGUS   <chr [1]> Obi-Wan Mahomey         
#> 2  2020     3 PEPE   <chr [1]> JuJu's Bizarre Adventure
#> 3  2020     4 BILL   <chr [1]> Bill's Fantasy Team     
#> 4  2020     5 CART   <chr [1]> Ashley Mattison         
#> 5  2020     6 KIER   <chr [1]> The Nuklear Option      
#> 6  2020     8 CORE   <chr [1]> Fuller Up               
#> 7  2020    10 NICK   <chr [1]> The Silence Of The Lamb 
#> 8  2020    11 KYLE   <chr [1]> Ashley Hill

The team_abbrev() function makes this conversion simple.

team_abbrev(id = 6, teams)
#> [1] KIER
#> Levels: AGUS PEPE BILL CART KIER CORE NICK KYLE

One caveat about the design of this package: most of the functions were designed and tested using the settings from the author’s own fantasy league. Functions relying on certain scoring or roster settings are particularly vulnerable for the time being. These settings can be referenced with the *_settings() functions and may be integrated in the future.

roster_settings()
#> $year
#> [1] 2020
#> 
#> $use_undrop
#> [1] FALSE
#> 
#> $lineup_lock
#> [1] "INDIVIDUAL_GAME"
#> 
#> $roster_lock
#> [1] "INDIVIDUAL_GAME"
#> 
#> $move_limit
#> [1] -1
#> 
#> $slot_count
#> QB RB WR TE DS PK BE IR FX 
#>  1  2  2  1  1  1  7  1  1 
#> 
#> $pos_count
#> QB RB WR TE PK DS 
#>  4  8  8  3  3  3
score_settings()
#> $year
#> [1] 2020
#> 
#> $score_type
#> [1] "H2H_POINTS"
#> 
#> $rank_type
#> [1] "STANDARD"
#> 
#> $home_bonus
#> [1] 0
#> 
#> $playoff_bonus
#> [1] 0
#> 
#> $playoff_tie
#> [1] "NONE"
#> 
#> $scoring
#> # A tibble: 44 x 3
#>     stat points overrides
#>    <int>  <dbl>     <dbl>
#>  1   132      0        -2
#>  2   133      0        -3
#>  3    98      0         4
#>  4    25      6        NA
#>  5   131      0        -1
#>  6   134      0        -4
#>  7    95      0         3
#>  8    72     -2        NA
#>  9   135      0        -5
#> 10   206      2         4
#> # … with 34 more rows

Players

There are over a thousand players in the NFL eligible for fantasy football. The full list of current players can be retrieved at any time.

all_players()
#> # A tibble: 1,072 x 19
#>     year  week     id first last  pro   pos   status start  rost change   prk  fpts   aav   adp
#>    <int> <dbl>  <int> <chr> <chr> <fct> <fct> <chr>  <dbl> <dbl>  <dbl> <int> <dbl> <dbl> <dbl>
#>  1  2020     8 3.05e6 Alvin Kama… NO    RB    A      0.979  1.00  0.042     1 124.   57.2  3.24
#>  2  2020     8 1.68e4 Dava… Adams GB    WR    A      0.981  1.00  0.041    15  68.9  44.2 11.0 
#>  3  2020     8 3.04e6 Derr… Henry Ten   RB    A      0.991  1.00  0.037     2 116.   54.9  5.21
#>  4  2020     8 1.58e4 Trav… Kelce KC    TE    A      0.996  1.00  0.023     1  78.1  35.0 18.3 
#>  5  2020     8 3.05e6 Ezek… Elli… Dal   RB    A      0.987  1.00  0.01      8  96.8  50.0  7.18
#>  6  2020     8 3.04e6 Geor… Kitt… SF    TE    A      0.987  1.00  0.046     2  57.2  33.9 20.3 
#>  7  2020     8 1.58e4 DeAn… Hopk… Ari   WR    A      0.607  1.00  0.026     4  86.4  42.8 12.2 
#>  8  2020     8 3.14e6 Patr… Maho… KC    QB    A      0.968  1.00  0.02      3 170.   24.6 19.6 
#>  9  2020     8 3.12e6 Tyre… Hill  KC    WR    A      0.983  1.00  0.018     5  85.3  23.1 27.5 
#> 10  2020     8 1.40e4 Julio Jones Atl   WR    Q      0.964  1.00  0.11     28  56.7  29.8 22.8 
#> # … with 1,062 more rows, and 4 more variables: next_wk <dbl>, last_wk <dbl>, last_szn <dbl>,
#> #   this_szn <dbl>

Each player is identified by their unique ID. Sometimes, only those player IDs are given. Team positions like defenses have negative IDs, but information on individual players can be retrieved from the generic ESPN (non-fantasy) API.

player_info(id = 3054850, row = TRUE)
#> # A tibble: 1 x 12
#>        id first last   pos   jersey weight height   age birth_date birth_place debut draft
#>     <dbl> <chr> <chr>  <chr> <chr>   <dbl>  <dbl> <int> <date>     <chr>       <int> <int>
#> 1 3054850 Alvin Kamara RB    41        215     70    25 1995-07-25 Atlanta, GA  2017    67

For your convenience, a table of active players is saved as a data frame.

nfl_players
#> # A tibble: 1,062 x 11
#>         id first   last    pro   pos   jersey weight height   age birth      debut
#>      <int> <chr>   <chr>   <fct> <fct> <chr>   <dbl>  <dbl> <int> <date>     <int>
#>  1 3051392 Ezekiel Elliott Dal   RB    21        228     72    25 1995-07-22  2016
#>  2 3054850 Alvin   Kamara  NO    RB    41        215     70    25 1995-07-25  2017
#>  3 3116593 Dalvin  Cook    Min   RB    33        210     70    25 1995-08-10  2017
#>  4   15795 DeAndre Hopkins Ari   WR    10        212     73    28 1992-06-06  2013
#>  5   15847 Travis  Kelce   KC    TE    87        260     77    30 1989-10-05  2013
#>  6 3116406 Tyreek  Hill    KC    WR    10        185     70    26 1994-03-01  2016
#>  7 3139477 Patrick Mahomes KC    QB    15        230     75    25 1995-09-17  2017
#>  8 3916387 Lamar   Jackson Bal   QB    8         212     74    23 1997-01-07  2018
#>  9   16800 Davante Adams   GB    WR    17        215     73    27 1992-12-24  2014
#> 10 3040151 George  Kittle  SF    TE    85        250     76    26 1993-10-09  2017
#> # … with 1,052 more rows

News on an individual player can also be helpful.

player_news(id = 15847)
#> # A tibble: 14 x 6
#>       id published           type   premium headline                     body                      
#>    <int> <dttm>              <chr>  <lgl>   <chr>                        <chr>                     
#>  1 15847 2020-10-26 01:57:11 Rotow… FALSE   Kelce caught all three of h… "The five-time Pro Bowler…
#>  2 15847 2020-10-20 00:31:47 Rotow… FALSE   Kelce caught five of seven … "Kelce got Kansas City on…
#>  3 15847 2020-10-11 21:34:23 Rotow… FALSE   Kelce brought in eight of 1… "The All-Pro tight end le…
#>  4 15847 2020-10-06 02:42:22 Rotow… FALSE   Kelce caught three of six t… "Kelce again led Kansas C…
#>  5 15847 2020-09-29 04:45:45 Rotow… FALSE   Kelce caught six of seven t… "Kelce led the Chiefs in …
#>  6 15847 2020-09-21 02:08:04 Rotow… FALSE   Kelce caught nine of 14 tar… "Kelce led the team in ta…
#>  7 15847 2020-09-11 04:24:20 Rotow… FALSE   Kelce brought in all six of… "The big tight end was pa…
#>  8 15847 2020-09-08 20:58:01 Rotow… FALSE   Kelce (knee) was a full par… "After being listed as a …
#>  9 15847 2020-09-08 10:32:10 Story  TRUE    Predicting 2020 NFL season … "<p><video1></video1></p>…
#> 10 15847 2020-09-07 23:10:05 Rotow… FALSE   Kelce (knee) was limited in… "Kelce has dealt with the…
#> 11 15847 2020-08-17 15:31:14 Story  FALSE   Inventing 32 props for the … "<p><video1></video1></p>…
#> 12 15847 2020-08-13 19:13:15 Rotow… FALSE   The Chiefs and Kelce agreed… "The exact parameters of …
#> 13 15847 2020-08-13 18:33:26 Rotow… FALSE   The Chiefs and Kelce are cl… "Parameters of the new co…
#> 14 15847 2020-02-03 04:23:02 Rotow… FALSE   Kelce brought in all six of… "Kelce's reception tally …

ESPN analysts publish weekly and preseason outlooks on most players.

outlooks <- player_outlook()
nrow(outlooks)

1 3360

cat(paste(">", outlooks$outlook[1]))

Kamara is coming off an up-and-down 2019 campaign, but the 24-year-old remains the main man in the New Orleans’ backfield. Kamara missed a pair of games but otherwise played a similar role to 2018, handling 12.2 carries and 7.0 targets per game. Kamara ended the season with a YPC above 4.5 and exactly 81 catches for the third consecutive season. A lack of usage near the goal line (7.1 OTD, 6 TDs) limited his fantasy production, though he did finish strongly with four of those scores coming during Weeks 16-17. Kamara should have little trouble pushing for 20 touches per game in the Saints’ Drew Brees-led, high-scoring offense. He remains a solid RB1.

Rosters

For the team rosters in your league, a list of data frames can be returned.

rosters <- team_roster()

The elements of this list are named for their team abbreviation.

rosters$KIER
#> # A tibble: 16 x 15
#>     year  week team  slot       id first  last    pro   pos   status  proj score start  rost change
#>    <int> <int> <fct> <fct>   <int> <chr>  <chr>   <fct> <fct> <chr>  <dbl> <dbl> <dbl> <dbl>  <dbl>
#>  1  2020     8 KIER  QB      14876 Ryan   Tanneh… Ten   QB    A      18.1     NA  42.4  81.4 27.2  
#>  2  2020     8 KIER  RB    3054850 Alvin  Kamara  NO    RB    A      15.3     NA  97.9 100.   0.042
#>  3  2020     8 KIER  RB    3025433 Mike   Davis   Car   RB    A      13.6     NA  94.7  98.9  1.52 
#>  4  2020     8 KIER  WR      15795 DeAnd… Hopkins Ari   WR    A       0       NA  60.7 100.   0.026
#>  5  2020     8 KIER  WR      16733 Odell  Beckha… Cle   WR    I       0       NA  52.8  89.8 -8.81 
#>  6  2020     8 KIER  TE      15847 Travis Kelce   KC    TE    A      10.3     NA  99.6 100.   0.023
#>  7  2020     8 KIER  FX    2508176 David  Johnson Hou   RB    A       0       NA  58.0  98.7  2.42 
#>  8  2020     8 KIER  DS     -16005 Browns D/ST    Cle   DS    A       3.92    NA  50.1  60.0 45.1  
#>  9  2020     8 KIER  PK      12460 Graham Gano    NYG   PK    Q       6.24    NA  54.5  65.2 36.2  
#> 10  2020     8 KIER  BE    2977187 Cooper Kupp    LAR   WR    A       8.90    NA  71.6  98.3  1.16 
#> 11  2020     8 KIER  BE    4242335 Jonat… Taylor  Ind   RB    A      12.1     NA  40.2  98.6  1.33 
#> 12  2020     8 KIER  BE    4035538 David  Montgo… Chi   RB    A      13.0     NA  78.5  98.0  5.17 
#> 13  2020     8 KIER  BE    3912550 Ronald Jones … TB    RB    A      11.0     NA  82.9  98.6  8.26 
#> 14  2020     8 KIER  BE    4038524 Gardn… Minshe… Jax   QB    A       0       NA  16.0  55.1 -5.54 
#> 15  2020     8 KIER  BE    3886818 Myles  Gaskin  Mia   RB    A      12.5     NA  40.4  94.9  6.97 
#> 16  2020     8 KIER  BE    3139522 Travis Fulgham Phi   WR    A       9.48    NA  60.4  83.7 36.6

We can easily identify the current starting roster, dropping bench players and those on injury reserve.

start_roster(rosters$KIER)
#> # A tibble: 9 x 15
#>    year  week team  slot       id first  last     pro   pos   status  proj score start  rost change
#>   <int> <int> <fct> <fct>   <int> <chr>  <chr>    <fct> <fct> <chr>  <dbl> <dbl> <dbl> <dbl>  <dbl>
#> 1  2020     8 KIER  QB      14876 Ryan   Tannehi… Ten   QB    A      18.1     NA  42.4  81.4 27.2  
#> 2  2020     8 KIER  RB    3054850 Alvin  Kamara   NO    RB    A      15.3     NA  97.9 100.   0.042
#> 3  2020     8 KIER  RB    3025433 Mike   Davis    Car   RB    A      13.6     NA  94.7  98.9  1.52 
#> 4  2020     8 KIER  WR      15795 DeAnd… Hopkins  Ari   WR    A       0       NA  60.7 100.   0.026
#> 5  2020     8 KIER  WR      16733 Odell  Beckham… Cle   WR    I       0       NA  52.8  89.8 -8.81 
#> 6  2020     8 KIER  TE      15847 Travis Kelce    KC    TE    A      10.3     NA  99.6 100.   0.023
#> 7  2020     8 KIER  FX    2508176 David  Johnson  Hou   RB    A       0       NA  58.0  98.7  2.42 
#> 8  2020     8 KIER  DS     -16005 Browns D/ST     Cle   DS    A       3.92    NA  50.1  60.0 45.1  
#> 9  2020     8 KIER  PK      12460 Graham Gano     NYG   PK    Q       6.24    NA  54.5  65.2 36.2

We can also easily filter for the starting roster that has the highest projected or past score. The score total for that roster can also be easily summed.

(best <- best_roster(rosters$KIER))
#> # A tibble: 9 x 14
#>    year  week team  slot       id first  last       pro   pos   status score start  rost change
#>   <int> <int> <fct> <fct>   <int> <chr>  <chr>      <fct> <fct> <chr>  <dbl> <dbl> <dbl>  <dbl>
#> 1  2020     8 KIER  QB      14876 Ryan   Tannehill  Ten   QB    A      18.1   42.4  81.4 27.2  
#> 2  2020     8 KIER  RB    3054850 Alvin  Kamara     NO    RB    A      15.3   97.9 100.   0.042
#> 3  2020     8 KIER  RB    3025433 Mike   Davis      Car   RB    A      13.6   94.7  98.9  1.52 
#> 4  2020     8 KIER  WR    3139522 Travis Fulgham    Phi   WR    A       9.48  60.4  83.7 36.6  
#> 5  2020     8 KIER  WR    2977187 Cooper Kupp       LAR   WR    A       8.90  71.6  98.3  1.16 
#> 6  2020     8 KIER  TE      15847 Travis Kelce      KC    TE    A      10.3   99.6 100.   0.023
#> 7  2020     8 KIER  FX    4035538 David  Montgomery Chi   RB    A      13.0   78.5  98.0  5.17 
#> 8  2020     8 KIER  DS     -16005 Browns D/ST       Cle   DS    A       3.92  50.1  60.0 45.1  
#> 9  2020     8 KIER  PK      12460 Graham Gano       NYG   PK    Q       6.24  54.5  65.2 36.2
roster_score(best)
#> [1] 98.78464

Players on a roster can also be compared against their professional schedule.

The 2020 NFL schedule is saved as the nfl_schedule table. This table might be out of date due to rescheduled games. The current schedule can be returned by pro_schedule(). The table also indicates if the games have started yet.

(sched <- ffl_merge(
  x = rosters$KIER[, 1:9], 
  y = pro_schedule()
))
#> # A tibble: 13 x 13
#>     year  week team  slot       id first  last   pro   pos   opp   home  kickoff             future
#>    <int> <int> <fct> <fct>   <int> <chr>  <chr>  <fct> <fct> <fct> <lgl> <dttm>              <lgl> 
#>  1  2020     8 KIER  QB      14876 Ryan   Tanne… Ten   QB    Cin   FALSE 2020-11-01 13:00:00 TRUE  
#>  2  2020     8 KIER  RB    3054850 Alvin  Kamara NO    RB    Chi   FALSE 2020-11-01 16:25:00 TRUE  
#>  3  2020     8 KIER  RB    3025433 Mike   Davis  Car   RB    Atl   TRUE  2020-10-29 20:20:00 TRUE  
#>  4  2020     8 KIER  WR      16733 Odell  Beckh… Cle   WR    LV    TRUE  2020-11-01 13:00:00 TRUE  
#>  5  2020     8 KIER  DS     -16005 Browns D/ST   Cle   DS    LV    TRUE  2020-11-01 13:00:00 TRUE  
#>  6  2020     8 KIER  TE      15847 Travis Kelce  KC    TE    NYJ   TRUE  2020-11-01 13:00:00 TRUE  
#>  7  2020     8 KIER  PK      12460 Graham Gano   NYG   PK    TB    TRUE  2020-11-02 20:15:00 TRUE  
#>  8  2020     8 KIER  BE    2977187 Cooper Kupp   LAR   WR    Mia   FALSE 2020-11-01 13:00:00 TRUE  
#>  9  2020     8 KIER  BE    4242335 Jonat… Taylor Ind   RB    Det   FALSE 2020-11-01 13:00:00 TRUE  
#> 10  2020     8 KIER  BE    4035538 David  Montg… Chi   RB    NO    TRUE  2020-11-01 16:25:00 TRUE  
#> 11  2020     8 KIER  BE    3912550 Ronald Jones… TB    RB    NYG   FALSE 2020-11-02 20:15:00 TRUE  
#> 12  2020     8 KIER  BE    3886818 Myles  Gaskin Mia   RB    LAR   TRUE  2020-11-01 13:00:00 TRUE  
#> 13  2020     8 KIER  BE    3139522 Travis Fulgh… Phi   WR    Dal   TRUE  2020-11-01 20:20:00 TRUE

The opponent teams for each player are ranked by the average points scored against them by each position. The lower the rank, the more points that position scores against the opponent team.

ffl_merge(
  x = sched[, 6:10], 
  y = opponent_ranks(), 
  by = c("pos", "opp" = "pro")
)
#> # A tibble: 12 x 7
#>    first    last        pro   pos   opp    rank   avg
#>    <chr>    <chr>       <fct> <fct> <fct> <int> <dbl>
#>  1 Ryan     Tannehill   Ten   QB    Cin      14 19.6 
#>  2 Alvin    Kamara      NO    RB    Chi      25 15.7 
#>  3 Mike     Davis       Car   RB    Atl       5 23.9 
#>  4 Odell    Beckham Jr. Cle   WR    LV        3 32.4 
#>  5 Browns   D/ST        Cle   DS    LV       14  2.93
#>  6 Travis   Kelce       KC    TE    NYJ      20  7.6 
#>  7 Cooper   Kupp        LAR   WR    Mia      31 16.1 
#>  8 Jonathan Taylor      Ind   RB    Det      27 14.9 
#>  9 David    Montgomery  Chi   RB    NO       20 17.3 
#> 10 Ronald   Jones II    TB    RB    NYG      28 14.8 
#> 11 Myles    Gaskin      Mia   RB    LAR       8 22.6 
#> 12 Travis   Fulgham     Phi   WR    Dal      12 25.6

Transactions

If you’re interested in how the players on a roster were acquired you look at either the acquisition history, draft picks, or league roster moves.

Every roster identifies players by acquisition method.

player_acquire()[[5]]
#> # A tibble: 16 x 11
#>     year  week team  slot       id first    last        pro   pos   method date               
#>    <int> <int> <fct> <fct>   <int> <chr>    <chr>       <fct> <fct> <chr>  <dttm>             
#>  1  2020     8 KIER  QB      14876 Ryan     Tannehill   Ten   QB    ADD    2020-10-21 12:00:34
#>  2  2020     8 KIER  RB    3054850 Alvin    Kamara      NO    RB    DRAFT  2020-09-06 22:17:42
#>  3  2020     8 KIER  RB    3025433 Mike     Davis       Car   RB    ADD    2020-09-23 11:00:09
#>  4  2020     8 KIER  WR      15795 DeAndre  Hopkins     Ari   WR    DRAFT  2020-09-06 22:17:42
#>  5  2020     8 KIER  WR      16733 Odell    Beckham Jr. Cle   WR    DRAFT  2020-09-06 22:17:42
#>  6  2020     8 KIER  TE      15847 Travis   Kelce       KC    TE    DRAFT  2020-09-06 22:17:42
#>  7  2020     8 KIER  FX    2508176 David    Johnson     Hou   RB    DRAFT  2020-09-06 22:17:42
#>  8  2020     8 KIER  DS     -16005 Browns   D/ST        Cle   DS    ADD    2020-10-21 12:00:34
#>  9  2020     8 KIER  PK      12460 Graham   Gano        NYG   PK    ADD    2020-10-21 12:00:34
#> 10  2020     8 KIER  BE    2977187 Cooper   Kupp        LAR   WR    DRAFT  2020-09-06 22:17:42
#> 11  2020     8 KIER  BE    4242335 Jonathan Taylor      Ind   RB    DRAFT  2020-09-06 22:17:42
#> 12  2020     8 KIER  BE    4035538 David    Montgomery  Chi   RB    DRAFT  2020-09-06 22:17:42
#> 13  2020     8 KIER  BE    3912550 Ronald   Jones II    TB    RB    DRAFT  2020-09-06 22:17:42
#> 14  2020     8 KIER  BE    4038524 Gardner  Minshew II  Jax   QB    ADD    2020-09-23 11:00:09
#> 15  2020     8 KIER  BE    3886818 Myles    Gaskin      Mia   RB    ADD    2020-09-30 11:01:14
#> 16  2020     8 KIER  BE    3139522 Travis   Fulgham     Phi   WR    ADD    2020-10-21 12:00:34

Roster moves are any waiver add, lineup change, or trade. Roster moves only identify players by their ID, so we will merge with the players table. The ffl_merge() function uses merge() to return a tibble of combined columns and rows in their same order.

ffl_merge(
  x = roster_moves()[, 7:14], 
  y = nfl_players[, 1:3]
)
#> # A tibble: 21 x 10
#>    date                 team from_slot from_team      id to_slot to_team move   first   last      
#>    <dttm>              <int> <fct>         <int>   <int> <fct>     <int> <chr>  <chr>   <chr>     
#>  1 2020-10-27 08:23:16     4 <NA>              4 2985659 <NA>         NA DROP   Wil     Lutz      
#>  2 2020-10-27 08:21:03     4 PK               NA 2985659 BE           NA LINEUP Wil     Lutz      
#>  3 2020-10-27 08:21:03     4 RB               NA 4360294 BE           NA LINEUP Antonio Gibson    
#>  4 2020-10-27 08:21:03     4 BE               NA 3116593 RB           NA LINEUP Dalvin  Cook      
#>  5 2020-10-27 08:21:03     4 BE               NA   16782 RB           NA LINEUP Jerick  McKinnon  
#>  6 2020-10-27 08:21:03     4 RB               NA 4052042 BE           NA LINEUP James   Robinson  
#>  7 2020-10-27 08:21:03     4 BE               NA   13229 TE           NA LINEUP Rob     Gronkowski
#>  8 2020-10-27 08:21:03     4 TE               NA 4036131 BE           NA LINEUP Noah    Fant      
#>  9 2020-10-27 08:21:03     4 BE               NA   15683 PK           NA LINEUP Justin  Tucker    
#> 10 2020-10-27 11:19:14     3 BE               NA 4259545 RB           NA LINEUP D'Andre Swift     
#> # … with 11 more rows

We can also get the entire history of the draft, either snake or auction.

ffl_merge(
  x = draft_picks(), 
  y = nfl_players[, 1:3]
)
#> # A tibble: 128 x 9
#>     year type     pick nominator  team   bid      id first     last          
#>    <int> <chr>   <int>     <int> <int> <int>   <int> <chr>     <chr>         
#>  1  2020 AUCTION     1         8     4    57 3929630 Saquon    Barkley       
#>  2  2020 AUCTION     2         3     8    33 3916387 Lamar     Jackson       
#>  3  2020 AUCTION     3        10     3    23 3120348 JuJu      Smith-Schuster
#>  4  2020 AUCTION     4        11     1     3    2330 Tom       Brady         
#>  5  2020 AUCTION     5         5     1    32 4045163 Miles     Sanders       
#>  6  2020 AUCTION     6         4     8    81 3117251 Christian McCaffrey     
#>  7  2020 AUCTION     7         1     5    45 4047365 Josh      Jacobs        
#>  8  2020 AUCTION     8         6    10     7   13229 Rob       Gronkowski    
#>  9  2020 AUCTION     9         8    10    52 3043078 Derrick   Henry         
#> 10  2020 AUCTION    10         3    11    32   16737 Mike      Evans         
#> # … with 118 more rows

A summary of transactions and moves is also available.

moves_summary()
#> # A tibble: 8 x 11
#>    year  week  team abbrev waiver spent acquisitions drops activated reserved trades
#>   <int> <int> <int> <fct>   <int> <int>        <int> <int>     <int>    <int>  <int>
#> 1  2020     8     1 AGUS        7    42           12    12        33        0      0
#> 2  2020     8     3 PEPE        5    33            8     7        31        2      0
#> 3  2020     8     4 BILL        8    83           13    13        45        4      0
#> 4  2020     8     5 CART        6    43            8     8        30        0      0
#> 5  2020     8     6 KIER        2    58           12    12        25        1      0
#> 6  2020     8     8 CORE        1    42           14    13        43        1      0
#> 7  2020     8    10 NICK        4    35           15    15        33        2      0
#> 8  2020     8    11 KYLE        3    43            9     8        31        1      0

Scores

Past team scores are found in the tidy tibble by matchup period.

match_scores()
#> # A tibble: 56 x 9
#>     year match week   team abbrev home  score winner power
#>    <int> <int> <fct> <int> <fct>  <lgl> <dbl> <lgl>  <dbl>
#>  1  2020     1 1         3 PEPE   TRUE  103.  TRUE       4
#>  2  2020     1 1         1 AGUS   FALSE  68.5 FALSE      0
#>  3  2020     2 1        10 NICK   TRUE   86.0 FALSE      1
#>  4  2020     2 1         4 BILL   FALSE 134.  TRUE       6
#>  5  2020     3 1         5 CART   TRUE  149.  TRUE       7
#>  6  2020     3 1        11 KYLE   FALSE  94.7 FALSE      2
#>  7  2020     4 1         8 CORE   TRUE  119.  TRUE       5
#>  8  2020     4 1         6 KIER   FALSE  99.7 FALSE      3
#>  9  2020     5 2         1 AGUS   TRUE  144.  TRUE       7
#> 10  2020     5 2         4 BILL   FALSE 110.  FALSE      2
#> # … with 46 more rows

These scores are only for matches played. We can also determine future matches.

match_schedule()
#> # A tibble: 96 x 6
#>     year  week match team  opp   home 
#>    <int> <int> <int> <fct> <fct> <lgl>
#>  1  2020     1     1 PEPE  AGUS  TRUE 
#>  2  2020     1     1 AGUS  PEPE  FALSE
#>  3  2020     1     2 NICK  BILL  TRUE 
#>  4  2020     1     2 BILL  NICK  FALSE
#>  5  2020     1     3 CART  KYLE  TRUE 
#>  6  2020     1     3 KYLE  CART  FALSE
#>  7  2020     1     4 CORE  KIER  TRUE 
#>  8  2020     1     4 KIER  CORE  FALSE
#>  9  2020     2     5 AGUS  BILL  TRUE 
#> 10  2020     2     5 BILL  AGUS  FALSE
#> # … with 86 more rows

If a matchup period is currently ongoing, the live score and projection can also be found.

live_scoring()
#> # A tibble: 8 x 5
#>    week match team  score  proj
#>   <int> <int> <fct> <dbl> <dbl>
#> 1     8    29 AGUS      0 101. 
#> 2     8    29 PEPE      0  92.9
#> 3     8    30 BILL      0  99.1
#> 4     8    30 NICK      0 115. 
#> 5     8    31 KYLE      0  80.0
#> 6     8    31 CART      0 108. 
#> 7     8    32 KIER      0  67.4
#> 8     8    32 CORE      0  85.2

It’s worth noting that matchups and weeks are different units of time. For this league, for example, regular season matchups last one week and playoff matches last two.

schedule_settings()
#> $year
#> [1] 2020
#> 
#> $divisions
#> # A tibble: 1 x 3
#>      id name   size
#>   <int> <chr> <int>
#> 1     0 East      8
#> 
#> $match_count
#> [1] 12
#> 
#> $match_length
#> [1] 1
#> 
#> $match_sched
#> # A tibble: 16 x 2
#>     week period
#>    <int> <chr> 
#>  1     1 1     
#>  2     2 2     
#>  3     3 3     
#>  4     4 4     
#>  5     5 5     
#>  6     6 6     
#>  7     7 7     
#>  8     8 8     
#>  9     9 9     
#> 10    10 10    
#> 11    11 11    
#> 12    12 12    
#> 13    13 13    
#> 14    14 13    
#> 15    16 14    
#> 16    15 14    
#> 
#> $period_type
#> [1] 1
#> 
#> $playoff_length
#> [1] 2
#> 
#> $seed_rule
#> [1] "TOTAL_POINTS_SCORED"
#> 
#> $playoff_size
#> [1] 4

If you want to return scores by week, use a different function. These functions also return “power wins” which are the total number of wins a team would get if they played every other team in the league; the lowest score gets zero power wins and the highest gets one less than the number of teams.

week_scores()
#> # A tibble: 56 x 8
#>     year match  week  team abbrev home  score power
#>    <int> <int> <dbl> <int> <fct>  <lgl> <dbl> <dbl>
#>  1  2020     1     1     3 PEPE   TRUE  103.      4
#>  2  2020     1     1     1 AGUS   FALSE  68.5     0
#>  3  2020     2     1    10 NICK   TRUE   86.0     1
#>  4  2020     2     1     4 BILL   FALSE 134.      6
#>  5  2020     3     1     5 CART   TRUE  149.      7
#>  6  2020     3     1    11 KYLE   FALSE  94.7     2
#>  7  2020     4     1     8 CORE   TRUE  119.      5
#>  8  2020     4     1     6 KIER   FALSE  99.7     3
#>  9  2020     5     2     1 AGUS   TRUE  144.      7
#> 10  2020     5     2     4 BILL   FALSE 110.      2
#> # … with 46 more rows

A summary of scores and wins is also available.

score_summary()
#> # A tibble: 8 x 16
#>    year  week  team abbrev draft current  seed final  back losses  ties  wins percentage against
#>   <int> <int> <int> <fct>  <int>   <int> <int> <int> <dbl>  <int> <int> <int>      <dbl>   <dbl>
#> 1  2020     8     1 AGUS       1       1     2    NA     0      2     0     5      0.714    707.
#> 2  2020     8     3 PEPE       7       6     4    NA     1      3     0     4      0.571    646.
#> 3  2020     8     4 BILL       8       3     1    NA     0      2     0     5      0.714    688.
#> 4  2020     8     5 CART       5       2     3    NA     1      3     0     4      0.571    690.
#> 5  2020     8     6 KIER       4       7     7    NA     3      5     0     2      0.286    759.
#> 6  2020     8     8 CORE       6       8     8    NA     3      5     0     2      0.286    816.
#> 7  2020     8    10 NICK       3       4     5    NA     2      4     0     3      0.429    701.
#> 8  2020     8    11 KYLE       2       5     6    NA     2      4     0     3      0.429    771.
#> # … with 2 more variables: points <dbl>, streak <dbl>

Historical

Most functions have an old argument that can be used to specify access to the historical endpoint of the API. If the recent data is usually returned as a dataframe, like rosters, then a list of dataframes is returned instead; if the recent data is a list, then a single dataframe is returned instead.

past <- week_scores(old = TRUE)
names(past) <- 2015:2019
str(past, max.level = 1)
#> List of 5
#>  $ 2015: tibble [136 × 8] (S3: tbl_df/tbl/data.frame)
#>  $ 2016: tibble [170 × 8] (S3: tbl_df/tbl/data.frame)
#>  $ 2017: tibble [160 × 8] (S3: tbl_df/tbl/data.frame)
#>  $ 2018: tibble [160 × 8] (S3: tbl_df/tbl/data.frame)
#>  $ 2019: tibble [128 × 8] (S3: tbl_df/tbl/data.frame)

str(league_info())
#> List of 6
#>  $ year  : int 2020
#>  $ name  : chr "Gambling Addicts Anonymous"
#>  $ id    : int 252353
#>  $ public: logi TRUE
#>  $ size  : int 8
#>  $ length: int 16
league_info(old = TRUE)
#> # A tibble: 5 x 6
#>    year name                           id public  size length
#>   <int> <chr>                       <int> <lgl>  <int>  <int>
#> 1  2015 Gambling Addicts Anonymous 252353 FALSE      8     17
#> 2  2016 Gambling Addicts Anonymous 252353 FALSE     10     17
#> 3  2017 Gambling Addicts Anonymous 252353 FALSE     10     16
#> 4  2018 Gambling Addicts Anonymous 252353 FALSE     10     16
#> 5  2019 Gambling Addicts Anonymous 252353 TRUE       8     16