fantasy

{fantasy} is a wrapper for the Fantasy Premier League API. It provides a clean, intuitive set of tidyverse-like functions to extract all the key data that is available from the API, as well as enabling actions such as transfers and team changes to be enacted programmatically.

After authenticating, the package provides a new class of object (<team>) that takes care of all the various restrictions on a team, so you can simply make transfers and substitutions and the package will notify you if they are not valid (e.g. more than 3 players from 1 club, not enough of a certain position in your team/starting XI, if a transfer exceeds your budget etc.). The <team> class also enables pretty printing of a team (see usage below).

It maintains a tidyverse-like style, with all functions returning tibbles with readable column names. The package also provides helper functions for obtaining data from other useful sources, such as predicted team lineups from fantasyfootballscout.co.uk or relevant tweets from twitter.

See the package site for more details.

WARNING: This package is experimental and once authenticated can make irreversible changes to your Fantasy Premier League team - you have been warned.

NOTE: Due to the nature of the Fantasy Premier League being an ongoing competition and the API being out of my control, it hasn’t been possible to fully test the package, so if you run into any problems please raise an issue and I’ll get round to it when I can.

Installation

You can install the development version of {fantasy} from GitHub with:

# install.packages("devtools")
devtools::install_github("chrisbrownlie/fantasy")

Motivation

There already exists at least two R packages that wrap the Fantasy Premier League API:

• fplR
• fplscrapR

The reasons for building {fantasy} are because the two packages above:

• Are not regularly maintained, and so may not work with the current (2022/23) version of the FPL API,
• Do not implement authentication, so cannot be used to perform actions and retrieve private user information, and
• Are not built using {httr2} and so do not benefit from some of its functionality.

{fantasy} aims to address all three of these.

Usage

Below are some examples of how to use the key functions in the package. See the {fantasy} site for more detailed information and examples.

There are generally two use (related) use cases for the {fantasy} package: analysing Fantasy Premier League data; and automating management of a Fantasy Premier League team. The two articles in the nav bar - ‘Extracting data’ and ‘Managing your team’ - address these two use cases in detail. If your use case is the latter of the two, I’d recommend reading ‘Authentication’ and ‘Managing your team’ before trying to enact any changes to your team.

# Get all fixtures from the current season
get_fixture_list()

# Get stats from a particular fixture, by ID
get_fixture_stats(fixture_id = 2)

# Authenticate to allow restricted actions - see vignette for more information
authenticate()

# See your team
my_team <- get_my_team()
my_team

After authenticating you can make changes to your team and submit them with update_team().

# Swap two players in your team
# - {fantasy} will automatically handle any restrictions or reordering of your team
# Substitutions and role changes can be made as many times as desired
my_team %>%
  team_substitute(p1 = 430, p2 = 199) %>%
  assign_role(pid = 28, role = "c") %>%
  assign_role(pid = 19, role = "vc")

Acknowledgements

This package wouldn’t be possible without the fantastic work of others such as the developers of the R packages used here - particularly httr2; dplyr and cli Fantasy Premier League themselves. Particular thanks also goes to Frenzel Timothy for giving the best overview of the Fantasy Premier League API endpoints.