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.
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:
With player ids:
Invalid or erring requests will not return any rows, the errors will be reported:
The functions are designed is such a way that they allow working with
the %>%
operator if the user desires to do so:
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:
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)
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: