The hardware and bandwidth for this mirror is donated by METANET, the Webhosting and Full Service-Cloud Provider.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]metanet.ch.

High-level players APIs

The high-level APIs intend to provide convenient functionality used by most users. Each function from the players API returns a data frame with the requested data processed to serve common purposes.

Note that while some of the showcased examples use the dplyr package to manipulate the data, the nhlapi package itself does not import it and the user is free to use whichever methods to manipulate the data.

library(nhlapi)

Players information

The first endpoint retrieves information on players based on provided player names or ids. This information includes data such as names, nationalities, birth dates, etc.

One or more names of one or more ids can be provided to the function, data on each valid player name or id will be returned as one row of the resulting data frame:

Example with player names, note that they are not case sensitive:

# Get information on players by name
nhl_players(c("joe sakic", "PETER forsberg"))

With player ids:

playerIds <- c(8451101, 8458554)
nhl_players(playerIds = playerIds)

Invalid or erring requests will not return any rows, the errors will be reported:

nhl_players(c("made up player", "Joe Sakic"))

nhl_players(playerIds = c("made up player", 8451101))

The functions are designed is such a way that they allow working with the %>% operator if the user desires to do so:

# Requires `dplyr` attached using library("dplyr")
nhl_players(playerIds = playerIds) %>%
  select(fullName, nationality, shootsCatches, primaryPosition.code)

Players' season statistics

The second endpoint is used to retrieve players' statistics per seasons. The function nhl_players_seasons() accepts multiple playerNames or playerIds and multiple seasons. The proper API URLs will be constructed and a flat data frame returned:

# Get a specific season statistics using player names
nhl_players_seasons(
  c("Joe SAKIC", "Peter Forsberg"),
  seasons = 1996:1998
)

It also accepts a playoff argument in case the users wants playoff statistics returned and not regular season:

# Get a specific season playoff statistics
nhl_players_seasons(
  c("Joe SAKIC", "Peter Forsberg"),
  seasons = 1996,
  playoffs = TRUE
)

Player ids can also be used instead of player names:

# Get a specific season playoff statistics
nhl_players_seasons(
  playerIds = c(8451101, 8458554),
  seasons = 1996,
  playoffs = TRUE
)

A simple wrapper nhl_players_allseasons() is also provided to get the statistics for all the seasons for the specified players:

# Get all season statistics for players
nhl_players_allseasons(playerIds = c(8451101, 8458554))

Combining the endpoints

The package outputs are designed in such a way that they support easy data manipulation and exploration. For instance, using the popular dplyr package:

# Requires `dplyr` attached using library
playerNames <- c("Joe Sakic", "Peter Forsberg")

result <- nhl_players(playerNames) %>%
  left_join(
    nhl_players_allseasons(playerNames),
    by = c("id" = "playerId")
  ) %>%
  filter(league.name == "National Hockey League") %>%
  select(fullName, seasonStart, stat.points)

head(result)

Plotting the data

The nhlapi package itself does not contain plotting functionality, the output of user-facing functions are however designed to be data frames adhering to principles that make plotting with popular packages very natural.

For instance, using the ggplot2 package to plot the amount of points gathered by multiple players over the seasons:

# Requires `ggplot2` attached using library
ggplot(result) +
  geom_line(aes(seasonStart, stat.points, colour = fullName))

Or using the highcharter package to create an interactive version of the same chart:

# Requires `highcharter` attached using library
result %>%
  hchart("line", hcaes(seasonStart, stat.points, group = fullName)) %>%
  hc_add_theme(hc_theme_google())

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.