Package {nhlscraper}

Title:	Scraper for National Hockey League Data
Version:	0.7.0
Description:	Scrapes and cleans data from the 'NHL' and 'ESPN' APIs into data.frames and lists. Wraps 125+ endpoints documented in https://github.com/RentoSaijo/nhlscraper/wiki from high-level multi-season summaries and award winners to low-level decisecond replays and bookmakers' odds, making them more accessible. Features cleaning and visualization tools, primarily for play-by-plays.
License:	GPL (≥ 3)
Encoding:	UTF-8
RoxygenNote:	7.3.3
Depends:	R (≥ 4.1.0)
Imports:	httr2 (≥ 1.2.0), jsonlite (≥ 2.0.0), xml2 (≥ 1.5.0), arrow (≥ 23.0.0), xgboost (≥ 3.2.0)
Suggests:	testthat (≥ 3.0.0), knitr (≥ 1.50.0), rmarkdown (≥ 2.29.0)
Config/testthat/edition:	3
VignetteBuilder:	knitr
URL:	https://rentosaijo.github.io/nhlscraper/, https://github.com/RentoSaijo/nhlscraper
BugReports:	https://github.com/RentoSaijo/nhlscraper/issues
Copyright:	NHL and the NHL Shield are registered trademarks of the National Hockey League. NHL and NHL team marks are the property of the NHL and its teams.
NeedsCompilation:	yes
Packaged:	2026-06-28 18:45:45 UTC; rsai_91
Author:	Rento Saijo [aut, cre, cph], Lars Skytte [ctb], Jack Pallotta [ctb]
Maintainer:	Rento Saijo <rentosaijo0527@gmail.com>
Repository:	CRAN
Date/Publication:	2026-06-28 19:10:02 UTC

nhlscraper: Scrape, clean, and visualize NHL data

Description

nhlscraper is an R package to scrape, clean, and visualize NHL data via the NHL and ESPN APIs. It primarily wraps 125+ endpoints from high-level multi-season summaries and award winners to low-level decisecond replays and bookmakers' odds, making them significantly more accessible. It also features cleaning and visualization functions, primarily for play-by-plays, to help analyze the data.

Prerequisite

• R/RStudio; you can check out my tutorial if you are not familiar.

Disclosure

Detailed documentation for each scraping function will be released gradually over time. Because each function can return a large amount of information, users are encouraged to explore the provided examples to discover what is available. Most, if not all, of the endpoints accessed by this package are unofficially documented (i.e., hidden), so it is important to use them responsibly and with respect for the NHL's data servers. Endpoints serving historical or otherwise mostly static data should ideally be queried once and then stored locally (for example, in a MySQL database) for further analysis, rather than being called repeatedly; the load functions attempt to mitigate this risk by providing pre-scraped data, so please make use of them. The exact rate limits for these APIs are not publicly known, so users are asked to avoid excessive or abusive querying to help ensure continued access for everyone.

History

Prior to the NHL API rework in 2023, Drew Hynes documented a comprehensive list of known endpoints, and several R packages, such as nhlapi and hockeyR, were built to access them. However, after the NHL completely transformed its API structure, all of these packages became mostly defunct as their authors understandably chose not to continue maintaining them. The community gathered around work by Zachary Maludzinski to discover and share new endpoints, but progress naturally slowed once most of the "main" endpoints were identified. Over the summer of 2025, I began reverse-engineering many of the remaining, undocumented endpoints while searching for additional data for future research, with a particular focus on NHL EDGE and Records data. After I shared those findings, the effort to expand and refine this map of the APIs accelerated, and with the addition of David Fleischer's effort, we ultimately identified 400+ new endpoints. In parallel, I also discovered many new endpoints for the ESPN API, extending beyond what Joseph Wilson had already compiled.

Author(s)

Maintainer: Rento Saijo rentosaijo0527@gmail.com (ORCID) [copyright holder]

Other contributors:

• Lars Skytte lars.sunesen.skytte@gmail.com [contributor]

• Jack Pallotta jackjpallotta@gmail.com (ORCID) [contributor]

See Also

Useful links:

• https://rentosaijo.github.io/nhlscraper/

• https://github.com/RentoSaijo/nhlscraper

• Report bugs at https://github.com/RentoSaijo/nhlscraper/issues

Initialize empty on-ice columns

Description

.add_empty_html_on_ice_columns() allocates empty scalar on-ice player ID and timing columns before HTML and shift-chart enrichment.

Usage

.add_empty_html_on_ice_columns(play_by_play, slot_count = NULL)

Arguments

Value

data.frame with empty on-ice columns added

Add HTML-derived on-ice players to play-by-play

Description

.add_html_on_ice_players() resolves HTML on-ice goalie and skater IDs, matches them to API rows, and injects the resulting scalar on-ice columns into play-by-play output.

Usage

.add_html_on_ice_players(
  play_by_play,
  game,
  rosters = NULL,
  home_team = NULL,
  away_team = NULL,
  html_rows = NULL
)

Arguments

Value

data.frame enriched with HTML-derived on-ice columns

Add on-ice shift timing context

Description

.add_on_ice_shift_timing_context() enriches play-by-play rows with scalar shift elapsed and since-last-shift columns for the on-ice goalies and skaters.

Usage

.add_on_ice_shift_timing_context(play_by_play, game, shift_data = NULL)

Arguments

Value

data.frame with scalar on-ice timing columns added

Add one-on-one shooter/goalie assignments

Description

.add_one_on_one_on_ice_players() populates on-ice player-ID columns for penalty-shot and shootout rows whose situationCode implies a one-skater versus one-goalie state (0101/1010). The raw situationCode remains the source column; this helper only synthesizes the compatible scalar player-ID assignments when the general HTML on-ice signature is not usable.

Usage

.add_one_on_one_on_ice_players(play_by_play, matched = data.frame())

Arguments

Value

data.frame enriched with one-on-one shooter/goalie assignments

Build a retrying API request

Description

.api_request() appends URL query parameters to a host/path pair and applies the package retry policy.

Usage

.api_request(base_url, path, query = list())

Arguments

Value

httr2 request object

Attach delta context columns to play-by-play

Description

.apply_pbp_delta_columns() inserts computed delta columns into a play-by-play and reorders them into the public schema.

Usage

.apply_pbp_delta_columns(play_by_play, delta_ctx)

Arguments

Value

data.frame with public delta columns inserted

Attach shot context columns to play-by-play

Description

.apply_shot_context() appends rush, rebound, and running score/attempt context columns to a play-by-play.

Usage

.apply_shot_context(play_by_play)

Arguments

Value

data.frame with shot context columns added

Assign resolved HTML on-ice IDs to scalar columns

Description

.assign_html_on_ice_player_ids() copies resolved HTML goalie and skater IDs into the public scalar on-ice player-ID columns for one play-by-play row.

Usage

.assign_html_on_ice_player_ids(
  play_by_play,
  idx,
  home_goalie,
  away_goalie,
  home_skaters,
  away_skaters
)

Arguments

Value

data.frame with scalar on-ice player-ID columns assigned for idx

Assign scalar on-ice timing metrics

Description

.assign_on_ice_shift_metric() copies goalie and skater timing matrices into home, away, for, and against scalar play-by-play columns.

Usage

.assign_on_ice_shift_metric(
  play_by_play,
  home_matrix,
  away_matrix,
  metric_suffix
)

Arguments

Value

data.frame with timing columns assigned

Backfill unmatched delayed-penalty rows from nearby populated rows

Description

.backfill_delayed_penalty_on_ice_players() fills unmatched delayed-penalty rows from the nearest previous populated supported row in the same game and period when the raw situationCode and goalie/skater counts are unchanged.

Usage

.backfill_delayed_penalty_on_ice_players(play_by_play, max_gap_seconds = 15L)

Arguments

Value

data.frame with delayed-penalty rows backfilled where possible

Build API-side HTML matching features

Description

.build_api_html_match_table() derives the API-side matching features used to align HTML play-by-play rows back to API play-by-play rows.

Usage

.build_api_html_match_table(play_by_play)

Arguments

Value

data.frame of API-side matching features

Build a game-roster lookup table

Description

.build_game_roster_lookup() standardizes roster columns and prepares a lookup table used to resolve HTML sweater numbers to player IDs.

Usage

.build_game_roster_lookup(rosters)

Arguments

Value

standardized roster lookup data.frame

Calculate the Euclidean angle from the attacking net for all the events (plays) in a play-by-play

Description

.calculate_angle() calculates the Euclidean angle from the attacking net for all the events (plays) in a play-by-play.

Usage

.calculate_angle(play_by_play)

Arguments

Value

data.frame with one row per event (play) and added angle column

Calculate the Euclidean distance from the attacking net for all the events (plays) in a play-by-play

Description

.calculate_distance() calculates the Euclidean distance from the attacking net for all the events (plays) in a play-by-play.

Usage

.calculate_distance(play_by_play)

Arguments

Value

data.frame with one row per event (play) and added distance column

Calculate shift times by situation from supplied data

Description

.calculate_shift_times_by_situation_data() is an internal helper for calculate_shift_times_by_situation().

Usage

.calculate_shift_times_by_situation_data(
  play_by_play,
  shift_chart,
  roster = NULL
)

Arguments

Value

Internal helper output.

Run shared public play-by-play cleanup

Description

.clean_public_pbp_plays() applies the common clock, ordering, strength, coordinate, shot-context, and HTML on-ice enrichment pipeline used by both GameCenter and World Showcase public play-by-play functions.

Usage

.clean_public_pbp_plays(
  plays,
  game,
  pbp_meta,
  html_rows,
  source = c("gc", "wsc")
)

Arguments

Value

data.frame in the finalized public play-by-play schema

Convert to the appropriate team ID

Description

Convert to the appropriate team ID

Usage

.coerce_team_id(team, lookup = .to_team_id)

Arguments

Value

integer in 1:68

Convert to the appropriate team three-letter code

Description

Convert to the appropriate team three-letter code

Usage

.coerce_team_tri_code(team, lookup = .to_team_tri_code)

Arguments

Value

three-letter code

Compute on-ice shift timings in R

Description

.compute_on_ice_shift_timing_in_r() is the pure-R fallback for resolving on-ice remaining-shift, elapsed-shift, and time-since-last-shift matrices.

Usage

.compute_on_ice_shift_timing_in_r(play_by_play, shift_data)

Arguments

Value

list containing home and away timing matrices

Compute on-ice shift timing matrices

Description

.compute_on_ice_shift_timing_matrices() uses the native timing resolver when available and falls back to the R implementation otherwise.

Usage

.compute_on_ice_shift_timing_matrices(play_by_play, shift_data)

Arguments

Value

list containing home and away timing matrices

Compute play-by-play deltas with native fallback

Description

.compute_pbp_deltas() validates the public schema, then uses the native delta routine when available and falls back to R otherwise.

Usage

.compute_pbp_deltas(play_by_play)

Arguments

Value

named list containing delta context vectors

Compute play-by-play deltas in R

Description

.compute_pbp_deltas_in_r() is the pure-R fallback for event-to-event delta calculations.

Usage

.compute_pbp_deltas_in_r(play_by_play)

Arguments

Value

named list containing delta context vectors

Compute shot context summaries

Description

.compute_shot_context() derives rush and rebound flags plus running goal, shot, Fenwick, and Corsi counts, using native code when available.

Usage

.compute_shot_context(play_by_play)

Arguments

Value

named list of logical and integer shot-context vectors

Count the as-of-event goal, shots on goal, Fenwick, and Corsi attempts and differentials for all the events (plays) in a play-by-play by perspective

Description

.count_goals_shots() counts the as-of-event goal, shots on goal, Fenwick, and Corsi attempts and differentials for all the events (plays) in a play-by-play by perspective.

Usage

.count_goals_shots(play_by_play)

Arguments

Value

data.frame with one row per event (play) and added columns: homeGoals, awayGoals, homeShots, awayShots, homeFenwick, awayFenwick, homeCorsi, awayCorsi, goalsFor, goalsAgainst, shotsFor, shotsAgainst, fenwickFor, fenwickAgainst, corsiFor, corsiAgainst, goalDifferential, shotDifferential, fenwickDifferential, and corsiDifferential

Identify Return-to-Play round-robin shootout games

Description

.covid_round_robin_shootout_game_ids() returns the 2019-20 round-robin seeding games that used regular-season overtime/shootout rules despite carrying playoff game IDs.

Usage

.covid_round_robin_shootout_game_ids()

Value

integer vector of game IDs

Convert dot-delimited names to camelCase

Description

Convert dot-delimited names to camelCase

Usage

.dot_to_camel(x)

Arguments

Value

character vector

Draw an arc on the rink

Description

.draw_rink_arc() draws an arc on the rink.

Usage

.draw_rink_arc(cx, cy, r, theta1, theta2, n = 100, col = "black", lwd = 1)

Arguments

Value

NULL

Draw a circle on the rink

Description

.draw_rink_circle() draws a circle on the rink.

Usage

.draw_rink_circle(x, y, r, n = 200, col = "black", lwd = 1)

Arguments

Value

NULL

Draw a shareable cumulative xG plot

Description

.draw_share_cumulative_xg() renders a home/away cumulative expected-goals time series.

Usage

.draw_share_cumulative_xg(series, labels, plot_title)

Arguments

Value

NULL, invisibly

Draw the shot-map legends

Description

.draw_share_shot_legends() draws outcome symbols and the xG color ramp above the rink.

Usage

.draw_share_shot_legends(scale, spec)

Arguments

Draw a shareable shot-location plot

Description

.draw_share_shot_locations() renders one team's shot attempts on the NHL rink with outcome symbols and xG color.

Usage

.draw_share_shot_locations(shots, plot_title, spec)

Arguments

Value

NULL, invisibly

Remove illogically ordered boundary events from a play-by-play

Description

.drop_illogical_ordered_events() removes stray boundary rows that can appear between a period's period-end and the following period's period-start. In practice, these are most often duplicated 0:00 faceoff/stoppage rows that are still tagged to the previous period even though the actual opening sequence for the next period follows immediately after.

Usage

.drop_illogical_ordered_events(play_by_play)

Arguments

Value

data.frame with illogically ordered boundary events removed

Build an empty play-by-play delta context

Description

.empty_pbp_delta_context() allocates an empty delta context sized to the number of play-by-play rows.

Usage

.empty_pbp_delta_context(n)

Arguments

Value

named list of empty delta vectors

Allocate a missing public play-by-play column

Description

.empty_public_pbp_column() returns a typed NA vector for a public play-by-play column that is absent in the upstream source data.

Usage

.empty_public_pbp_column(name, n)

Arguments

Value

typed vector of missing values

Ensure a native symbol is available

Description

.ensure_local_native_symbol() checks whether a native symbol is already registered and, if needed, tries to load the installed package shared object. It does not trust the current working directory.

Usage

.ensure_local_native_symbol(symbol)

Arguments

Value

logical scalar indicating whether the symbol is available

Call the ESPN API

Description

.espn_api() performs a retrying request against the ESPN site or core API and parses the JSON response with the same flattening rules used for NHL API calls.

Usage

.espn_api(path, query = list(), type)

Arguments

Value

parsed JSON object, usually a data.frame or nested list

Extract an HTML clock token

Description

.extract_html_clock() extracts the first MM:SS-style clock from a report cell.

Usage

.extract_html_clock(x)

Arguments

Value

character scalar or NA_character_

Fetch HTML on-ice play-by-play rows

Description

.fetch_html_pbp_on_ice() downloads an NHL HTML play-by-play report and parses its on-ice content into a structured data frame.

Usage

.fetch_html_pbp_on_ice(
  game,
  rosters,
  home_team_id,
  away_team_id,
  home_abbrev,
  away_abbrev
)

Arguments

Value

data.frame of parsed HTML play-by-play rows

Finalize public play-by-play output

Description

.finalize_pbp_output() selects and orders the final GC or WSC public play-by-play column set.

Usage

.finalize_pbp_output(play_by_play, source = c("gc", "wsc"))

Arguments

Value

data.frame with the finalized public play-by-play schema

Flag if the event belongs to the home team or not for all the events (plays) in a play-by-play

Description

.flag_is_home() flags if the event belongs to the home team or not for all the events (plays) in a play-by-play.

Usage

.flag_is_home(play_by_play)

Arguments

Value

data.frame with one row per event (play) and added isHome column

Flag if the shot attempt is a rebound attempt or creates a rebound for all the shots in a play-by-play

Description

.flag_is_rebound() flags whether a shot attempt is a rebound attempt (i.e., taken within 3 seconds of a prior blocked, missed, or saved attempt with no stoppage in between), and whether a shot attempt creates a rebound under the same definition.

Usage

.flag_is_rebound(play_by_play)

Arguments

Value

data.frame with one row per event (play) and added columns: createdRebound and isRebound

Flag if the shot attempt is a rush attempt or not for all the shots in a play-by-play

Description

.flag_is_rush() flags whether a shot attempt is a rush attempt, defined as any shot attempt occurring within 4 seconds of a prior event in the neutral or defensive zone with no stoppage in play in between.

Usage

.flag_is_rush(play_by_play)

Arguments

Value

data.frame with one row per event (play) and added isRush column

Format elapsed seconds as an MM:SS clock

Description

.format_elapsed_clock() converts elapsed-in-period seconds back into zero-padded MM:SS strings.

Usage

.format_elapsed_clock(seconds)

Arguments

Value

character vector

Format an HTML shift clock

Description

.format_html_shift_clock() validates an extracted MM:SS clock and returns the zero-padded public shift-chart form.

Usage

.format_html_shift_clock(x)

Arguments

Value

character scalar or NA_character_

Compute period base seconds for a game

Description

.game_period_base_seconds() returns elapsed-game seconds at the start of each period under regular-season or playoff overtime rules.

Usage

.game_period_base_seconds(game, period_number)

Arguments

Value

integer vector

Identify populated on-ice player rows

Description

.has_any_on_ice_player_ids() returns a logical vector indicating whether a play-by-play row already has any scalar on-ice player IDs assigned.

Usage

.has_any_on_ice_player_ids(play_by_play)

Arguments

Value

logical vector

Convert clocks to seconds

Description

.html_clocks_to_seconds() vectorizes .html_time_to_seconds() for shift report clock columns.

Usage

.html_clocks_to_seconds(x)

Arguments

Value

integer vector

Resolve the owner team from an HTML description

Description

.html_desc_owner_team_id() infers the event owner team ID from the leading team abbreviation embedded in an HTML event description.

Usage

.html_desc_owner_team_id(
  description,
  home_abbrev,
  away_abbrev,
  home_team_id,
  away_team_id
)

Arguments

Value

integer team ID or NA_integer_

Map HTML event codes to event type keys

Description

.html_event_code_to_type_desc() converts HTML report event codes and select description fallbacks into internal play-by-play event type keys.

Usage

.html_event_code_to_type_desc(event_code, description = NA_character_)

Arguments

Value

event type key or NA_character_

Extract actor player IDs from an HTML event

Description

.html_extract_actor_player_ids() resolves primary, secondary, and tertiary actor player IDs from HTML event descriptions using the roster lookup.

Usage

.html_extract_actor_player_ids(
  description,
  type_desc_key,
  owner_team_id,
  home_team_id,
  away_team_id,
  home_abbrev,
  away_abbrev,
  roster_lookup
)

Arguments

Value

named list of actor player IDs

Extract team-tagged player references from HTML

Description

.html_extract_tagged_players() resolves explicitly team-tagged HTML player references such as TOR #42 into ordered team/player pairs.

Usage

.html_extract_tagged_players(
  description,
  home_team_id,
  away_team_id,
  home_abbrev,
  away_abbrev,
  roster_lookup
)

Arguments

Value

data.frame of ordered team/player references

Build the HTML play-by-play report URL

Description

.html_pbp_report_url() returns the NHL HTML play-by-play report URL for a game.

Usage

.html_pbp_report_url(game)

Arguments

Value

character scalar URL

Build an HTML report request

Description

.html_report_request() constructs an HTML report request with the same retry policy used for API calls.

Usage

.html_report_request(url)

Arguments

Value

httr2 request object

Build the HTML shift report URL

Description

.html_shift_report_url() returns a team-specific NHL HTML shift report URL for a game. team_tag is usually TH for the home report or TV for the away report.

Usage

.html_shift_report_url(game, team_tag)

Arguments

Value

character scalar URL

Convert a clock duration to seconds

Description

.html_time_to_seconds() converts MM:SS or HH:MM:SS strings to seconds.

Usage

.html_time_to_seconds(x)

Arguments

Value

integer scalar or NA_integer_

Resolve a roster player ID

Description

.lookup_roster_player_id() resolves a player ID from team, sweater number, and optional name information within a roster lookup table.

Usage

.lookup_roster_player_id(
  roster_lookup,
  team_id,
  sweater_number,
  player_name = NA_character_
)

Arguments

Value

integer player ID or NA_integer_

Mask HTML on-ice columns on unsupported events

Description

.mask_strength_context_block() sets HTML-derived on-ice player-ID and timing columns to NA on event types that are not supported by the HTML on-ice player pipeline.

Usage

.mask_strength_context_block(play_by_play)

Arguments

Value

data.frame with unsupported rows masked

Match HTML play-by-play rows to API rows

Description

.match_html_pbp_to_api() aligns parsed HTML play-by-play rows back to API play-by-play rows using exact keys, greedy scoring, and a reciprocal-best fallback for duplicate clusters.

Usage

.match_html_pbp_to_api(play_by_play, html_rows)

Arguments

Value

data.frame of matched HTML rows with apiIndex

Call the NHL API

Description

.nhl_api() performs a retrying request against one of the NHL API hosts and parses the JSON response with the package's standard flattening rules.

Usage

.nhl_api(path, query = list(), type)

Arguments

Value

parsed JSON object, usually a data.frame or nested list

Parse an NHL API response as JSON

Description

.nhl_json_from_response() converts an httr2 response object into parsed JSON using the package's standard UTF-8 and flattening settings.

Usage

.nhl_json_from_response(resp)

Arguments

Value

parsed JSON (i.e., data.frame or list)

Build an NHL API request

Description

.nhl_request() selects the requested NHL API host and constructs a retrying request object. It is used by public wrappers that need to fetch requests in parallel before parsing the body.

Usage

.nhl_request(path, query = list(), type)

Arguments

Value

httr2 request object

Build a Hugging Face NHL_DB parquet URL

Description

.nhldb_url() builds URLs for the season-level parquet snapshots used by the bulk loaders.

Usage

.nhldb_url(path)

Arguments

Value

character scalar URL

Normalize the x and y coordinates for all the events (plays) in a play-by-play

Description

.normalize_coordinates() normalizes the x and y coordinates for all the events (plays) in a play-by-play such that they all attack towards +x. If homeTeamDefendingSide is not available, the home defending side in period 1 is inferred using zoneCode, isHome, and xCoord.

Usage

.normalize_coordinates(play_by_play)

Arguments

Value

data.frame with one row per event (play) and added columns xCoordNorm and yCoordNorm

Normalize an HTML team abbreviation

Description

.normalize_html_team_abbrev() uppercases and strips punctuation from HTML team abbreviations so dotted legacy abbreviations still match.

Usage

.normalize_html_team_abbrev(x)

Arguments

Value

normalized character vector

Normalize locale-style dotted columns to camelCase

Description

Converts dotted names (e.g., firstName.default, name.cs) to camelCase and removes trailing Default from default-language fields.

Usage

.normalize_locale_names(x)

Arguments

Value

character vector

Normalize raw/internal play-by-play names to the public schema

Description

.normalize_public_pbp_names() renames the raw GameCenter/World Showcase column names used during ingest into the current public play-by-play schema. This helper is for the package's own ingest pipeline only and is not a legacy-input compatibility layer for downstream callers.

Usage

.normalize_public_pbp_names(play_by_play)

Arguments

Value

data.frame with current public column names where available

Normalize roster person labels

Description

.normalize_roster_person() standardizes roster names for stable matching by uppercasing, trimming, collapsing whitespace, and transliterating accents.

Usage

.normalize_roster_person(x)

Arguments

Value

normalized character vector

Normalize situation codes for parsing

Description

.normalize_situation_code_for_parse() pads 1-4 digit situation codes to four characters for internal parsing without rewriting the source column.

Usage

.normalize_situation_code_for_parse(situation_code)

Arguments

Value

character vector of parse-ready situation codes

Normalize team abbreviation columns to team tri-code names

Description

Normalize team abbreviation columns to team tri-code names

Usage

.normalize_team_abbrev_cols(x)

Arguments

Value

character vector

Normalize the team key

Description

Normalize the team key

Usage

.normalize_team_key(team)

Arguments

Value

integer in 1:68, character full name, OR three-letter code

List on-ice player ID columns

Description

.on_ice_id_scalar_column_names() returns the public scalar goalie and skater ID column names used in enriched play-by-play outputs.

Usage

.on_ice_id_scalar_column_names(play_by_play = NULL, slot_count = NULL)

Arguments

Value

character vector of on-ice player ID columns

Extract an integer on-ice column

Description

.on_ice_int_col() safely extracts an integer column from a data frame and returns NA values when the column is absent.

Usage

.on_ice_int_col(df, name)

Arguments

Value

integer vector

List all scalar on-ice columns

Description

.on_ice_scalar_column_names() returns the scalar on-ice player ID and shift-timing columns used by the public play-by-play schema.

Usage

.on_ice_scalar_column_names(play_by_play = NULL, slot_count = NULL)

Arguments

Value

character vector of scalar on-ice columns

Return the tracked number of on-ice skater slots

Description

.on_ice_skater_slots() returns the current number of skater slots tracked per team in play-by-play outputs. It guarantees the standard five skater columns and expands further when the input already contains overflow skater slots or when a caller requests a larger slot count.

Usage

.on_ice_skater_slots(play_by_play = NULL, slot_count = NULL, min_slots = 5L)

Arguments

Value

integer scalar

Build scalar on-ice timing column names

Description

.on_ice_timing_scalar_column_names() returns the scalar goalie and skater timing column names for a timing metric suffix.

Usage

.on_ice_timing_scalar_column_names(
  metric_suffix,
  play_by_play = NULL,
  slot_count = NULL
)

Arguments

Value

character vector of column names

Open a PNG device for a share plot

Description

.open_share_png() opens the output device only when save is TRUE.

Usage

.open_share_png(file_name, spec, save)

Arguments

Value

logical indicating whether a device was opened

Parse optional HTML on-ice rows from a parallel response

Description

.optional_html_pbp_rows_from_response() parses a fetched HTML play-by-play response when it succeeded and otherwise returns an empty data frame.

Usage

.optional_html_pbp_rows_from_response(
  resp,
  game,
  rosters,
  home_team_id,
  away_team_id,
  home_abbrev,
  away_abbrev
)

Arguments

Value

data.frame of parsed HTML rows or an empty data.frame

Pad public situation codes

Description

.pad_public_situation_code() preserves missing values and zero-pads nonempty situation codes to the four-character public play-by-play form.

Usage

.pad_public_situation_code(play_by_plays)

Arguments

Value

data.frame

Check whether a parallel request failed

Description

.parallel_request_failed() returns TRUE when a response object from .perform_parallel_requests() is an httr2 failure.

Usage

.parallel_request_failed(resp)

Arguments

Value

logical scalar

Parse an HTML elapsed clock

Description

.parse_html_elapsed_clock() extracts the elapsed MM:SS clock from an HTML report time field and converts it to elapsed seconds in period.

Usage

.parse_html_elapsed_clock(x)

Arguments

Value

integer seconds elapsed in period or NA_integer_

Parse an HTML on-ice cell

Description

.parse_html_on_ice_cell() resolves a goalie and skater player-ID list from a single team on-ice HTML cell.

Usage

.parse_html_on_ice_cell(text, team_id, roster_lookup)

Arguments

Value

named list containing goalie and skater player IDs

Parse an HTML play-by-play document

Description

.parse_html_pbp_doc() extracts event rows, actor IDs, and on-ice player lists from an NHL HTML play-by-play report.

Usage

.parse_html_pbp_doc(
  doc,
  roster_lookup,
  home_team_id,
  away_team_id,
  home_abbrev,
  away_abbrev,
  is_playoffs = FALSE
)

Arguments

Value

data.frame of parsed HTML play-by-play rows

Parse an HTML on-ice play-by-play response

Description

.parse_html_pbp_response() converts an already-fetched HTML play-by-play response into parsed on-ice rows.

Usage

.parse_html_pbp_response(
  resp,
  game,
  rosters,
  home_team_id,
  away_team_id,
  home_abbrev,
  away_abbrev
)

Arguments

Value

data.frame of parsed HTML play-by-play rows

Parse an HTML period label

Description

.parse_html_period_label() converts HTML report period labels such as OT and SO into integer period numbers.

Usage

.parse_html_period_label(x, is_playoffs = FALSE)

Arguments

Value

integer period number or NA_integer_

Parse situation-code components

Description

.parse_situation_code_components() converts situation codes into away/home goalie and skater counts without mutating the original source vector.

Usage

.parse_situation_code_components(situation_code)

Arguments

Value

integer matrix with away/home goalie and skater counts

List public delta column names

Description

.pbp_delta_public_cols() returns the public-facing delta columns inserted by add_deltas().

Usage

.pbp_delta_public_cols()

Value

character vector of public delta column names

Perform multiple requests concurrently

Description

.perform_parallel_requests() executes a list of httr2 requests with libcurl multi support and preserves the input names on the output.

Usage

.perform_parallel_requests(reqs, on_error = c("stop", "return", "continue"))

Arguments

Value

list of responses or httr2 failure objects

Prepare raw GameCenter rows for public cleanup

Description

.prepare_gc_public_pbp_plays() normalizes the flattened GameCenter event names and source-specific quirks before the shared public play-by-play cleaning pipeline runs.

Usage

.prepare_gc_public_pbp_plays(plays, game)

Arguments

Value

data.frame

Prepare raw World Showcase rows for public cleanup

Description

.prepare_wsc_public_pbp_plays() normalizes the World Showcase event feed and removes source-only fields before the shared public play-by-play cleanup pipeline runs.

Usage

.prepare_wsc_public_pbp_plays(plays, game)

Arguments

Value

data.frame

Identify shootout-eligible games for public play-by-play cleanup

Description

.public_pbp_is_shootout_eligible() returns TRUE for games whose overtime rules follow the regular-season shootout path.

Usage

.public_pbp_is_shootout_eligible(game_id, game_type_id)

Arguments

Value

logical vector

Derive the legal period length in seconds

Description

.public_pbp_legal_period_seconds() returns the nominal legal length for each play-by-play row's period under the relevant game context.

Usage

.public_pbp_legal_period_seconds(game_id, game_type_id, period)

Arguments

Value

integer vector of legal period lengths in seconds

Download and read a remote parquet file

Description

.read_remote_parquet() downloads a parquet file to a temporary path and returns it as a base data.frame.

Usage

.read_remote_parquet(path, timeout = NULL, method = NULL)

Arguments

Value

data.frame

Repair public play-by-play clock/order defects in boundary-row feeds

Description

.repair_public_pbp_sequence() removes rows with impossible clocks and reorders explicit-boundary feeds into a more coherent public sequence. The repair is intentionally scoped to the modern boundary-row era, where the audited issues are dominated by stale sort-order markers, early period-end rows, and opening faceoffs that arrive after live-play rows.

Usage

.repair_public_pbp_sequence(play_by_play)

Arguments

Value

data.frame with repaired clocks and ordering where feasible

Add the package retry policy to a request

Description

.request_with_retry() retries transient 429 rate-limit responses with a short exponential backoff.

Usage

.request_with_retry(req)

Arguments

Value

httr2 request object

Validate required public play-by-play columns

Description

.require_public_pbp_columns() errors when a public helper is called with a play-by-play missing required public schema columns.

Usage

.require_public_pbp_columns(play_by_play, cols, fn_name)

Arguments

Value

NULL, invisibly, or an error if required columns are missing

Validate required shift-chart columns

Description

.require_shift_chart_columns() errors when a helper is called with a shift chart missing required public schema columns.

Usage

.require_shift_chart_columns(shift_chart, cols, fn_name)

Arguments

Value

NULL, invisibly, or an error if required columns are missing

Scope generic person-name columns to an entity

Description

Scope generic person-name columns to an entity

Usage

.scope_person_name_cols(x, prefix)

Arguments

Value

character vector

Score HTML-to-API matching candidates

Description

.score_html_api_candidates() scores candidate API rows for a single HTML row using time, type, team, player, and local sequence agreement.

Usage

.score_html_api_candidates(api, html, cand, h_idx, last_api_seq = NULL)

Arguments

Value

named numeric vector of candidate scores

Build a cumulative xG title

Description

.share_cumulative_title() builds the title for a game-level cumulative xG time series.

Usage

.share_cumulative_title(labels)

Arguments

Value

character scalar

Build cumulative xG series

Description

.share_cumulative_xg_series() converts shot-attempt rows into home and away step-series vectors.

Usage

.share_cumulative_xg_series(shots, play_by_play)

Arguments

Value

named list of cumulative xG series

Filter share shots to one team

Description

.share_filter_team_shots() keeps home or away shot-attempt rows.

Usage

.share_filter_team_shots(shots, team)

Arguments

Value

data.frame

Read game labels for share plots

Description

.share_game_labels() fetches the GameCenter summary and extracts the team abbreviations and game date used in plot titles.

Usage

.share_game_labels(game)

Arguments

Value

named list of game labels

Fetch shot attempts with xG for a game

Description

.share_game_shots() retrieves a game play-by-play, scores expected goals, and keeps public shot-attempt rows used by share plots.

Usage

.share_game_shots(game)

Arguments

Value

named list containing the full play-by-play and shot rows

Build share-plot output settings

Description

.share_plot_spec() returns file naming, canvas size, and legend offsets for an IG or X plot.

Usage

.share_plot_spec(platform, plot_type)

Arguments

Value

named list of plot settings

Build a shot-location title

Description

.share_shot_location_title() builds the title for a team-specific shot map.

Usage

.share_shot_location_title(labels, team)

Arguments

Value

character scalar

Normalize share-plot team selector

Description

.share_team_key() converts home/away shorthands into the canonical team key used by share plots.

Usage

.share_team_key(team)

Arguments

Value

character scalar, either home or away

Build xG color scaling metadata

Description

.share_xg_scale() caps xG at the 98th percentile of positive attempts and returns colors plus legend labels on a log-like scale.

Usage

.share_xg_scale(xg)

Arguments

Value

named list of color and legend metadata

Add team and player metadata

Description

.shift_situation_add_metadata() is an internal helper for calculate_shift_times_by_situation().

Usage

.shift_situation_add_metadata(summary, roster = NULL)

Arguments

Value

Internal helper output.

Add situation total columns

Description

.shift_situation_add_totals() is an internal helper for calculate_shift_times_by_situation().

Usage

.shift_situation_add_totals(summary, overlaps)

Arguments

Value

Internal helper output.

Summarize player-period shift totals

Description

.shift_situation_base_summary() is an internal helper for calculate_shift_times_by_situation().

Usage

.shift_situation_base_summary(shift_chart)

Arguments

Value

Internal helper output.

Identify game team IDs

Description

.shift_situation_game_teams() is an internal helper for calculate_shift_times_by_situation().

Usage

.shift_situation_game_teams(play_by_play, shift_chart)

Arguments

Value

Internal helper output.

Build shift-situation intervals

Description

.shift_situation_intervals() is an internal helper for calculate_shift_times_by_situation().

Usage

.shift_situation_intervals(play_by_play, shift_chart)

Arguments

Value

Internal helper output.

Read lookup column with fallback

Description

.shift_situation_lookup_col() is an internal helper for calculate_shift_times_by_situation().

Usage

.shift_situation_lookup_col(source, col, fallback)

Arguments

Value

Internal helper output.

Order shift-situation output columns

Description

.shift_situation_order_output() is an internal helper for calculate_shift_times_by_situation().

Usage

.shift_situation_order_output(summary)

Arguments

Value

Internal helper output.

Intersect shifts with situation intervals

Description

.shift_situation_overlaps() is an internal helper for calculate_shift_times_by_situation().

Usage

.shift_situation_overlaps(shift_chart, intervals)

Arguments

Value

Internal helper output.

Compute shift-situation overlaps in R

Description

.shift_situation_overlaps_in_r() is an internal helper for calculate_shift_times_by_situation().

Usage

.shift_situation_overlaps_in_r(shift_chart, intervals)

Arguments

Value

Internal helper output.

Convert situation codes to player-team perspective

Description

.shift_situation_perspective_code() is an internal helper for calculate_shift_times_by_situation().

Usage

.shift_situation_perspective_code(situation_code, player_is_home)

Arguments

Value

Internal helper output.

Build player metadata lookup

Description

.shift_situation_player_lookup() is an internal helper for calculate_shift_times_by_situation().

Usage

.shift_situation_player_lookup(roster = NULL)

Arguments

Value

Internal helper output.

Build a shot-event mask

Description

.shot_event_mask() flags play-by-play rows matching selected event types.

Usage

.shot_event_mask(play_by_play, types)

Arguments

Value

logical vector

Sort shift data for timing lookups

Description

.sort_shift_chart_for_timing() filters incomplete shift rows and sorts the remainder into the order expected by the timing resolvers.

Usage

.sort_shift_chart_for_timing(shift_data)

Arguments

Value

filtered and sorted shift data.frame

Strip the game ID into the season ID, game type ID, and game number for all the events (plays) in a play-by-play

Description

.strip_game_id() strips the game ID into season ID, game type ID, and game number for all the events (plays) in a play-by-play.

Usage

.strip_game_id(play_by_play)

Arguments

Value

data.frame with one row per event (play) and added columns: seasonId, gameTypeId, and gameNumber

Strip the situation code into goalie and skater counts, man differential, and strength state for all the events (plays) in a play-by-play by perspective

Description

.strip_situation_code() strips the situation code into goalie and skater counts for home and away teams, then (from the event owner's perspective) computes man differential and a strength state classification without rewriting the source situationCode column.

Usage

.strip_situation_code(play_by_play)

Arguments

Value

data.frame with one row per event (play) and added columns: homeIsEmptyNet, awayIsEmptyNet, homeSkaterCount, awaySkaterCount, isEmptyNetFor, isEmptyNetAgainst, skaterCountFor, skaterCountAgainst, manDifferential, and strengthState

Strip the timestamp and period number into the time elapsed in the period and game for all the events (plays) in a play-by-play

Description

.strip_time_period() strips the timestamp and period number into the time elapsed in the period and game for all the events (plays) in a play-by-play.

Usage

.strip_time_period(play_by_play)

Arguments

Value

data.frame with one row per event (play) and added columns secondsElapsedInPeriod and secondsElapsedInGame

List HTML on-ice player-ID event types

Description

.supported_html_on_ice_id_event_types() returns the event types that are allowed to receive HTML-derived on-ice player IDs.

Usage

.supported_html_on_ice_id_event_types()

Value

character vector of supported on-ice player-ID event type keys

List strength-context event types

Description

.supported_strength_event_types() returns the event types that support the HTML row-matching pipeline.

Usage

.supported_strength_event_types()

Value

character vector of supported event type keys

Convert to the appropriate game type ID

Description

Convert to the appropriate game type ID

Usage

.to_game_type_id(game_type)

Arguments

Value

integer in 1:3

Read xG auto-download option

Description

.xg_auto_download() is an internal helper for calculate_expected_goals().

Usage

.xg_auto_download()

Value

Internal helper output.

Bake xG model matrix

Description

.xg_bake_matrix() is an internal helper for calculate_expected_goals().

Usage

.xg_bake_matrix(data, spec)

Arguments

Value

Internal helper output.

Build xG booster URL

Description

.xg_booster_url() is an internal helper for calculate_expected_goals().

Usage

.xg_booster_url(path)

Arguments

Value

Internal helper output.

Build xG model frame

Description

.xg_build_model_frame() is an internal helper for calculate_expected_goals().

Usage

.xg_build_model_frame(shots, play_by_play)

Arguments

Value

Internal helper output.

Build skater-slot matrix

Description

.xg_build_skater_matrix() is an internal helper for calculate_expected_goals().

Usage

.xg_build_skater_matrix(data, suffix, mode = "numeric")

Arguments

Value

Internal helper output.

Locate bundled xG metadata

Description

.xg_bundle_path() is an internal helper for calculate_expected_goals().

Usage

.xg_bundle_path()

Value

Internal helper output.

Build xG bundle cache version

Description

.xg_bundle_version() is an internal helper for calculate_expected_goals().

Usage

.xg_bundle_version(bundle = .xg_load_bundle())

Arguments

Value

Internal helper output.

Resolve cached xG booster path

Description

.xg_cache_booster_path() is an internal helper for calculate_expected_goals().

Usage

.xg_cache_booster_path(path)

Arguments

Value

Internal helper output.

Locate xG cache directory

Description

.xg_cache_dir() is an internal helper for calculate_expected_goals().

Usage

.xg_cache_dir()

Value

Internal helper output.

Build cached xG booster path

Description

.xg_cached_booster_path() is an internal helper for calculate_expected_goals().

Usage

.xg_cached_booster_path(path, bundle = .xg_load_bundle())

Arguments

Value

Internal helper output.

Get default xG model base URL

Description

.xg_default_model_base_url() is an internal helper for calculate_expected_goals().

Usage

.xg_default_model_base_url()

Value

Internal helper output.

Download xG booster file

Description

.xg_download_booster() is an internal helper for calculate_expected_goals().

Usage

.xg_download_booster(row, bundle = .xg_load_bundle())

Arguments

Value

Internal helper output.

Encode categorical xG feature

Description

.xg_encode_categorical() is an internal helper for calculate_expected_goals().

Usage

.xg_encode_categorical(values, var, spec, n)

Arguments

Value

Internal helper output.

Read expected xG booster checksum

Description

.xg_expected_booster_sha256() is an internal helper for calculate_expected_goals().

Usage

.xg_expected_booster_sha256(row)

Arguments

Value

Internal helper output.

Locate xG extdata directory

Description

.xg_extdata_dir() is an internal helper for calculate_expected_goals().

Usage

.xg_extdata_dir()

Value

Internal helper output.

Extract matched skater-slot value

Description

.xg_extract_matched_value() is an internal helper for calculate_expected_goals().

Usage

.xg_extract_matched_value(id_mat, value_mat, player_id)

Arguments

Value

Internal helper output.

Extract skater slot indices

Description

.xg_extract_slot_indices() is an internal helper for calculate_expected_goals().

Usage

.xg_extract_slot_indices(data, suffix)

Arguments

Value

Internal helper output.

Fetch shift data for xG features

Description

.xg_fetch_shift_data() is an internal helper for calculate_expected_goals().

Usage

.xg_fetch_shift_data(game_ids)

Arguments

Value

Internal helper output.

Fill goalie-against fallback columns

Description

.xg_fill_goalie_against_fallback() is an internal helper for calculate_expected_goals().

Usage

.xg_fill_goalie_against_fallback(play_by_play)

Arguments

Value

Internal helper output.

Flag inner-slot shots

Description

.xg_is_inner_slot_shot() is an internal helper for calculate_expected_goals().

Usage

.xg_is_inner_slot_shot(x_coord_norm, abs_y_coord_norm)

Arguments

Value

Internal helper output.

Flag net-front shots

Description

.xg_is_net_front_shot() is an internal helper for calculate_expected_goals().

Usage

.xg_is_net_front_shot(x_coord_norm, abs_y_coord_norm)

Arguments

Value

Internal helper output.

Flag slot shots

Description

.xg_is_slot_shot() is an internal helper for calculate_expected_goals().

Usage

.xg_is_slot_shot(x_coord_norm, abs_y_coord_norm)

Arguments

Value

Internal helper output.

Load xG booster model

Description

.xg_load_booster() is an internal helper for calculate_expected_goals().

Usage

.xg_load_booster(model_key, bundle = .xg_load_bundle())

Arguments

Value

Internal helper output.

Load xG model bundle

Description

.xg_load_bundle() is an internal helper for calculate_expected_goals().

Usage

.xg_load_bundle()

Value

Internal helper output.

Build previous event type key

Description

.xg_make_type_desc_key_prev() is an internal helper for calculate_expected_goals().

Usage

.xg_make_type_desc_key_prev(
  type_desc_key_prev,
  reason_prev,
  shot_type_prev,
  event_owner_team_id_prev,
  event_owner_team_id
)

Arguments

Value

Internal helper output.

Read xG model base URL option

Description

.xg_model_base_url() is an internal helper for calculate_expected_goals().

Usage

.xg_model_base_url()

Value

Internal helper output.

Find xG model index row

Description

.xg_model_index_row() is an internal helper for calculate_expected_goals().

Usage

.xg_model_index_row(model_key, bundle = .xg_load_bundle())

Arguments

Value

Internal helper output.

Build xG model key

Description

.xg_model_key() is an internal helper for calculate_expected_goals().

Usage

.xg_model_key(target_season, partition)

Arguments

Value

Internal helper output.

Normalize xG missed-shot reason

Description

.xg_normalize_missed_reason() is an internal helper for calculate_expected_goals().

Usage

.xg_normalize_missed_reason(x)

Arguments

Value

Internal helper output.

Normalize xG shot type

Description

.xg_normalize_shot_type() is an internal helper for calculate_expected_goals().

Usage

.xg_normalize_shot_type(x)

Arguments

Value

Internal helper output.

Partition shots by game state

Description

.xg_partition_shots() is an internal helper for calculate_expected_goals().

Usage

.xg_partition_shots(shots)

Arguments

Value

Internal helper output.

Compute xG percentile rank

Description

.xg_percent_rank() is an internal helper for calculate_expected_goals().

Usage

.xg_percent_rank(x)

Arguments

Value

Internal helper output.

Prepare play-by-play for xG scoring

Description

.xg_prepare_play_by_play() is an internal helper for calculate_expected_goals().

Usage

.xg_prepare_play_by_play(play_by_play)

Arguments

Value

Internal helper output.

Resolve remote xG booster path

Description

.xg_remote_booster_path() is an internal helper for calculate_expected_goals().

Usage

.xg_remote_booster_path(path)

Arguments

Value

Internal helper output.

Require current public play-by-play schema

Description

.xg_require_current_public_schema() is an internal helper for calculate_expected_goals().

Usage

.xg_require_current_public_schema(play_by_play)

Arguments

Value

Internal helper output.

Identify required xG shift columns

Description

.xg_required_shift_cols() is an internal helper for calculate_expected_goals().

Usage

.xg_required_shift_cols(play_by_play)

Arguments

Value

Internal helper output.

Resolve xG booster file path

Description

.xg_resolve_booster_path() is an internal helper for calculate_expected_goals().

Usage

.xg_resolve_booster_path(
  model_key,
  bundle = .xg_load_bundle(),
  download = TRUE
)

Arguments

Value

Internal helper output.

Compute row maximums with missing values

Description

.xg_row_max() is an internal helper for calculate_expected_goals().

Usage

.xg_row_max(mat)

Arguments

Value

Internal helper output.

Compute row means with missing values

Description

.xg_row_mean() is an internal helper for calculate_expected_goals().

Usage

.xg_row_mean(mat)

Arguments

Value

Internal helper output.

Compute row medians with missing values

Description

.xg_row_median() is an internal helper for calculate_expected_goals().

Usage

.xg_row_median(mat)

Arguments

Value

Internal helper output.

Compute row minimums with missing values

Description

.xg_row_min() is an internal helper for calculate_expected_goals().

Usage

.xg_row_min(mat)

Arguments

Value

Internal helper output.

Score shots with xGBoost

Description

.xg_score_xgboost() is an internal helper for calculate_expected_goals().

Usage

.xg_score_xgboost(df, model_key, bundle = .xg_load_bundle())

Arguments

Value

Internal helper output.

Select xG target season

Description

.xg_select_target_season() is an internal helper for calculate_expected_goals().

Usage

.xg_select_target_season(game_id, bundle = .xg_load_bundle())

Arguments

Value

Internal helper output.

Coerce xG feature to logical

Description

.xg_to_logical() is an internal helper for calculate_expected_goals().

Usage

.xg_to_logical(x)

Arguments

Value

Internal helper output.

Validate xG booster path

Description

.xg_validate_booster_path() is an internal helper for calculate_expected_goals().

Usage

.xg_validate_booster_path(path)

Arguments

Value

Internal helper output.

Validate xG model bundle

Description

.xg_validate_bundle() is an internal helper for calculate_expected_goals().

Usage

.xg_validate_bundle(bundle)

Arguments

Value

Internal helper output.

Verify xG booster file checksum

Description

.xg_verify_booster_file() is an internal helper for calculate_expected_goals().

Usage

.xg_verify_booster_file(path, row)

Arguments

Value

Internal helper output.

Warn about ignored xG model argument

Description

.xg_warn_ignored_model() is an internal helper for calculate_expected_goals().

Usage

.xg_warn_ignored_model(model, fn_name)

Arguments

Value

Internal helper output.

Add event-to-event deltas to a play-by-play

Description

add_deltas() adds event-to-event deltas in raw and normalized x/y, distance, and angle for a play-by-play. Sequences are bounded by faceoffs: each sequence begins at a faceoff, faceoff rows do not look backward across the boundary, and subsequent events are compared to the most recent prior valid-spatial event in the same faceoff-bounded sequence. Shootout and penalty-shot rows (0101/1010) are left as NA and do not serve as anchors for later rows. When multiple events in a sequence share the same recorded second, zero-time denominators used internally are replaced by 1 / n, where n is the number of events in that same second within the sequence.

Usage

add_deltas(play_by_play)

Arguments

Value

data.frame with one row per event (play) and added columns: eventIdPrev, secondsElapsedInSequence, dSecondsElapsedInSequence, dXCoord, dYCoord, dXCoordNorm, dYCoordNorm, dDistance, dAngle, dXCoordPerSecond, dYCoordPerSecond, dXCoordNormPerSecond, dYCoordNormPerSecond, dDistancePerSecond, dAnglePerSecond

Add goalie biometrics to (a) play-by-play(s)

Description

add_goalie_biometrics() adds goalie biometrics (height, weight, hand, and age at game date) to (a) play-by-play(s) for shot attempts. Goalie identity is resolved from goalieInNetId first and goaliePlayerIdAgainst second. If neither is available on a row, the added goalie biometrics are left as NA.

Usage

add_goalie_biometrics(play_by_play)

Arguments

Value

data.frame with one row per event (play) and added columns: goalieHeight, goalieWeight, goalieHandCode, and goalieAge

Add on-ice shift times to a play-by-play

Description

add_shift_times() adds SecondsRemainingInShift, SecondsElapsedInShift, and SecondsElapsedInPeriodSinceLastShift columns for the on-ice goalies and skaters already present in a public play-by-play. It accepts either a single game play-by-play plus shift_chart() data or a season aggregate plus shift_charts() data.

Usage

add_shift_times(play_by_play, shift_chart)

Arguments

Value

data.frame with one row per event (play) and added or updated scalar on-ice shift timing columns

Examples

  pbp <- gc_play_by_play(game = 2023030417)
  sc  <- shift_chart(game = 2023030417)
  pbp <- add_shift_times(pbp, sc)

Add shooter biometrics to (a) play-by-play(s)

Description

add_shooter_biometrics() adds shooter biometrics (height, weight, hand, age at game date, and position) to (a) play-by-play(s) for shot attempts.

Usage

add_shooter_biometrics(play_by_play)

Arguments

Value

data.frame with one row per event (play) and added columns: shooterHeight, shooterWeight, shooterHandCode, shooterAge, and shooterPositionCode

Access the attendance by season and game type

Description

attendance() returns records-site attendance totals by season and game type.

Usage

attendance()

Value

data.frame with one row per season

Examples

all_attendance <- attendance()

Access all the award winners/finalists

Description

award_winners() returns historical trophy winners and finalists with one row per player/season/status entry.

Usage

award_winners()

Value

data.frame with one row per winner/finalist

Examples

all_award_winners <- award_winners()

Access all the awards

Description

awards() returns the records-site trophy catalog with one row per award and normalized trophy IDs, names, and short names.

Usage

awards()

Value

data.frame with one row per award

Examples

all_awards <- awards()

Access the boxscore for a game, team, and position

Description

boxscore() returns one side of the GameCenter boxscore for one position group. Each row is a player with normalized name/position fields and the game-stat columns exposed for that group.

Usage

boxscore(game = 2023030417, team = "home", position = "forwards")

Arguments

Value

data.frame with one row per player

Examples

boxscore_COL_forwards_Martin_Necas_legacy_game <- boxscore(
  game     = 2025020275,
  team     = 'H',
  position = 'F'
)

Access the playoff bracket for a season

Description

bracket() returns the public playoff bracket for one season, with one row per series and normalized team, seed, score, and series-status fields.

Usage

bracket(season = season_now())

Arguments

Value

data.frame with one row per series

Examples

bracket_20242025 <- bracket(season = 20242025)

Calculate the expected goals for all the shots in (a) play-by-plays

Description

calculate_expected_goals() scores shot events with nhlscraper's rolling XGBoost expected-goals models. The package ships the small preprocessing bundle and downloads needed boosters from the companion NHLxG model store into a local user cache on first use. Each shot is routed to the matching season vintage and one of six game-state partitions: sd (5v5), ev (other even strength), pp (power play), sh (short-handed), en (empty net against), and ps (penalty shot; trained on penalty-shot and shootout-style rows). The legacy model argument is accepted for backward compatibility but ignored.

Usage

calculate_expected_goals(play_by_play, model = NULL)

calculate_xG(play_by_play, model = NULL)

Arguments

Value

data.frame with one row per event (play) and added xG column

Examples

# May take >5s, so skip.

  pbp <- gc_play_by_play()
  pbp_with_xg <- calculate_expected_goals(play_by_play = pbp)

Calculate shift times by exact situation code

Description

calculate_shift_times_by_situation() returns one row per player per period and splits time on ice by the exact play-by-play situationCode in effect during that player's shifts. This differs from shift_chart_summary(), which reads the NHL HTML report's broad EV/PP/SH totals. Here, shift seconds come from shift_chart() and strength state comes from gc_play_by_play(). When season is supplied, it overrides game and the function uses gc_play_by_plays() with shift_charts() for the full season.

Usage

calculate_shift_times_by_situation(game = 2023030417, season = NULL)

Arguments

Details

In the play-by-play, the four situationCode digits mean away goalie count, away skater count, home skater count, and home goalie count. In this output, the four digits in each situation-specific column mean player-team goalie count, player-team skater count, opponent skater count, and opponent goalie count. For example, raw 1451 means home skaters are on a 5-on-4 power play; those seconds are written to ⁠1541TimeOnIce⁠ for home players and ⁠1451TimeOnIce⁠ for away players.

Value

data.frame with one row per player per period and situation-specific TimeOnIce columns

Examples

shift_situations_2023030417 <- calculate_shift_times_by_situation(
  game = 2023030417
)

Access the career statistics for all the coaches

Description

coach_career_statistics() returns regular-season plus playoff career coaching records with one row per coach.

Usage

coach_career_statistics()

coach_career_stats()

Value

data.frame with one row per coach

Examples

coach_career_stats <- coach_career_statistics()

Access the statistics for all the coaches by franchise and game type

Description

coach_franchise_statistics() returns coach records by franchise and game type, with one row per coach/franchise/game-type stint.

Usage

coach_franchise_statistics()

coach_franchise_stats()

Value

data.frame with one row per franchise per coach per game type

Examples

coach_franchise_stats <- coach_franchise_statistics()

Access all the coaches

Description

coaches() returns the records-site coach registry with one row per coach and normalized coach IDs, names, and birth fields.

Usage

coaches()

Value

data.frame with one row per coach

Examples

all_coaches <- coaches()

Access the draft combine reports

Description

combine_reports() returns draft-combine measurements and test results with one row per player/event result.

Usage

combine_reports()

Value

data.frame with one row per player

Examples

combine_reports <- combine_reports()

Access all contracts from packaged internal data

Description

contracts() loads preprocessed contract records bundled with the package, resolves each row to an NHL player ID when the player registry has a clear match, drops unresolved/ambiguous matches, and returns normalized contract seasons and money fields.

Usage

contracts()

Value

data.frame with one row per contract

Examples

all_contracts <- contracts()

Access all the countries

Description

countries() returns the stats API country catalog with one row per country and normalized two-/three-letter country fields.

Usage

countries()

Value

data.frame with one row per country

Examples

all_countries <- countries()

Access all the draft picks

Description

draft_picks() returns the historical draft-pick table with one row per pick, including draft year/round/overall slot, team, player, position, and biographical fields.

Usage

draft_picks()

Value

data.frame with one row per pick

Examples

# May take >5s, so skip.
all_draft_picks <- draft_picks()

Access all the draft prospects

Description

draft_prospects() returns the records-site prospect registry with one row per prospect and normalized prospect/player IDs, names, birth data, and profile fields.

Usage

draft_prospects()

Value

data.frame with one row per player

Examples

# May take >5s, so skip.
all_prospects <- draft_prospects()

Access the draft rankings for a class and category

Description

draft_rankings() returns NHL Central Scouting rankings for one draft class and skater/goalie region group, with one row per ranked prospect.

Usage

draft_rankings(class = season_now()%%10000, category = 1)

Arguments

Value

data.frame with one row per player

Examples

draft_rankings_INTL_Skaters_2017 <- draft_rankings(
  class    = 2017, 
  category = 2
)

Access the real-time draft tracker

Description

draft_tracker() returns the live NHL draft tracker picks for the current draft, with normalized player, team, round, and pick fields.

Usage

draft_tracker()

Value

data.frame with one row per player

Examples

draft_tracker <- draft_tracker()

Access all the drafts

Description

drafts() merges the records draft master and stats draft-round endpoints, returning one row per draft year with IDs, dates, location, and round metadata.

Usage

drafts()

Value

data.frame with one row per draft

Examples

all_drafts <- drafts()

Draw a full NHL rink

Description

draw_NHL_rink() draws a full NHL rink such that the x and y coordinates span -100 to 100 and -43 to +43, respectively. Use graphics::points() to create custom graphs; check out an example on the online documentation!

Usage

draw_NHL_rink()

Value

NULL

Examples

draw_NHL_rink()

Access the ESPN futures for a season

Description

espn_futures() returns ESPN futures markets for one season with one row per future type and nested book/odds detail retained in ESPN's payload columns.

Usage

espn_futures(season = season_now())

Arguments

Value

nested data.frame with one row per type (outer) and book (inner)

Examples

ESPN_futures_20252026 <- espn_futures(20252026)

Access the ESPN odds for a game

Description

espn_game_odds() returns ESPN's odds items for one game with one row per provider/market entry and camelCase names for nested price, spread, and total fields.

Usage

espn_game_odds(game = 401777460)

Arguments

Value

data.frame with one row per provider

Examples

ESPN_odds_SCF_20242025 <- espn_game_odds(game = 401777460)

Access the ESPN summary for a game

Description

espn_game_summary() returns ESPN's competition summary for one game after dropping large availability/link/detail blocks, leaving the compact game, competitor, venue, date, format, and series fields exposed by the core API.

Usage

espn_game_summary(game = 401777460)

Arguments

Value

list with various items

Examples

ESPN_summary_SCF_20242025 <- espn_game_summary(game = 401777460)

Access the ESPN games for a season

Description

espn_games() pages ESPN's NHL event index for a season and returns one row per event containing the ESPN game ID used by the other ESPN wrappers.

Usage

espn_games(season = season_now())

Arguments

Value

data.frame with one row per ESPN game

Examples

ESPN_games_20242025 <- espn_games(season = 20242025)

Access the real-time ESPN injury reports

Description

espn_injuries() returns ESPN's current injury report with one outer row per team and nested player injury details where ESPN includes them.

Usage

espn_injuries()

Value

nested data.frame with one row per team (outer) and player (inner)

Examples

ESPN_injuries_now <- espn_injuries()

Access the ESPN play-by-play for a game

Description

espn_play_by_play() returns ESPN's play rows for one game with one row per event, normalized event IDs, period labels, clock/text fields, team refs, and coordinate fields when ESPN supplies them.

Usage

espn_play_by_play(game = 401777460)

espn_pbp(game = 401777460)

Arguments

Value

data.frame with one row per event (play)

Examples

ESPN_pbp_SCF_20242025 <- espn_play_by_play(game = 401777460)

Access the ESPN summary for a player

Description

espn_player_summary() returns a compact one-row ESPN athlete profile with name, birth, size, handedness, draft, debut, position, experience, and active status fields.

Usage

espn_player_summary(player = 3988803)

Arguments

Value

data.frame with one row

Examples

ESPN_summary_Charlie_McAvoy <- espn_player_summary(player = 3988803)

Access all the ESPN players

Description

espn_players() pages ESPN's athlete index and returns one row per athlete containing the ESPN player ID used by espn_player_summary().

Usage

espn_players()

Value

data.frame with one row per ESPN player

Examples

all_ESPN_players <- espn_players()

Access the ESPN summary for a team

Description

espn_team_summary() returns a compact one-row ESPN team profile with location, display names, abbreviation, and active status.

Usage

espn_team_summary(team = 1)

Arguments

Value

data.frame with one row

Examples

ESPN_summary_Boston_Bruins <- espn_team_summary(team = 1)

Access all the ESPN teams

Description

espn_teams() pages ESPN's team index and returns one row per team containing the ESPN team ID used by espn_team_summary().

Usage

espn_teams()

Value

data.frame with one row per ESPN team

Examples

all_ESPN_teams <- espn_teams()

Access the ESPN transactions for a season

Description

espn_transactions() pages ESPN's transaction feed across a season window and returns one row per transaction with normalized team fields.

Usage

espn_transactions(season = season_now())

Arguments

Value

data.frame with one row per transaction

Examples

ESPN_transactions_20242025 <- espn_transactions(season = 20242025)

Access all the expansion draft picks

Description

expansion_draft_picks() returns historical expansion-draft picks with one row per selected player/team/season combination.

Usage

expansion_draft_picks()

Value

data.frame with one row per pick

Examples

all_expansion_draft_picks <- expansion_draft_picks()

Access all the expansion drafts

Description

expansion_drafts() returns expansion-draft rule records by season, including the rule text and season identifiers exposed by the records endpoint.

Usage

expansion_drafts()

Value

data.frame with one row per expansion draft

Examples

all_expansion_drafts <- expansion_drafts()

Access the playoff series results for all the franchises by situation

Description

franchise_playoff_situational_results() returns playoff series records by franchise and series situation, such as leading or trailing a series.

Usage

franchise_playoff_situational_results()

Value

data.frame with one row per franchise per situation

Examples

franchise_playoff_situational_results <- 
  franchise_playoff_situational_results()

Access the statistics for all the franchises by season and game type

Description

franchise_season_statistics() returns records-site franchise results by season and game type, including team, standing, record, goals, and points fields.

Usage

franchise_season_statistics()

franchise_season_stats()

Value

data.frame with one row per franchise per season per game type

Examples

# May take >5s, so skip.
franchise_season_stats <- franchise_season_statistics()

Access the all-time statistics for all the franchises by game type

Description

franchise_statistics() returns all-time franchise totals by game type, including games, wins/losses, goals, points, and related aggregate fields.

Usage

franchise_statistics()

franchise_stats()

Value

data.frame with one row per franchise per game type

Examples

franchise_stats <- franchise_statistics()

Access the all-time statistics for all the franchises by team and game type

Description

franchise_team_statistics() returns all-time totals by franchise-era team and game type, preserving separate rows for teams that share a franchise.

Usage

franchise_team_statistics()

franchise_team_stats()

Value

data.frame with one row per team per franchise per game type

Examples

franchise_team_stats <- franchise_team_statistics()

Access the all-time statistics versus other franchises for all the franchises by game type

Description

franchise_versus_franchise() returns all-time head-to-head records by franchise, opponent franchise, and game type.

Usage

franchise_versus_franchise()

franchise_vs_franchise()

Value

data.frame with one row per franchise per franchise per game type

Examples

# May take >5s, so skip.
franchise_vs_franchise <- franchise_versus_franchise()

Access all the franchises

Description

franchises() merges records-site franchise and franchise-detail metadata, returning one row per franchise with normalized franchise/team identifiers and names.

Usage

franchises()

Value

data.frame with one row per franchise

Examples

all_franchises <- franchises()

Access the real-time game odds for a country by partnered bookmaker

Description

game_odds() returns the public partner-game feed for one country, with one row per current game and normalized team, game type, bookmaker, and odds fields when NHL exposes them.

Usage

game_odds(country = "US")

Arguments

Value

data.frame with one row per game

Examples

game_odds_CA <- game_odds(country = 'CA')

Access the rosters for a game

Description

game_rosters() returns the roster spots from a GameCenter play-by-play payload with one row per dressed player, including team ID, sweater number, position, and normalized player name fields.

Usage

game_rosters(game = 2023030417)

Arguments

Value

data.frame with one row per player

Examples

rosters_Martin_Necas_legacy_game <- game_rosters(game = 2025020275)

Access the game type as of now

Description

game_type_now() retrieves the game type as of now and returns a scalar integer used as the current-context default in season/game-type dependent wrappers.

Usage

game_type_now()

Value

integer in 1:3 (where 1 = pre-season, 2 = regular season, 3 = playoff/post-season)

Examples

game_type_now <- game_type_now()

Access all the games

Description

games() returns the stats API game catalog with one row per NHL game, ordered by gameId and normalized to gameId, seasonId, and gameTypeId.

Usage

games()

Value

data.frame with one row per game

Examples

# May take >5s, so skip.
all_games <- games()

Access the GameCenter (GC) play-by-play for a game

Description

gc_play_by_play() retrieves the GameCenter (GC) play-by-play for a game as a data.frame where each row represents an event. The returned schema is the cleaned, public-facing play-by-play schema, including canonical names such as periodNumber, eventTypeCode, eventTypeDescKey, homeShots, shotsFor, penaltyTypeDescKey, penaltyDuration, servedByPlayerId, goalieInNetId, and HTML-report-derived on-ice player ID columns such as homeGoaliePlayerId, awayGoaliePlayerId, homeSkater1PlayerId, and any additional overflow skater slots required by the game. HTML report skater and goalie IDs are returned whenever they can be matched back to a supported row, even when the raw situationCode is stale. Use add_shift_times() with shift_chart() (or shift_charts()) to add on-ice shift timing columns.

Usage

gc_play_by_play(game = 2023030417)

gc_pbp(game = 2023030417)

Arguments

Value

data.frame with one row per event (play)

Examples

# May take >5s, so skip.
gc_pbp_Martin_Necas_legacy_game <- gc_play_by_play(game = 2025020275)

Access the raw GameCenter (GC) play-by-play for a game

Description

gc_play_by_play_raw() returns the raw flattened GameCenter play-by-play as served by the NHL API for one game. Use gc_play_by_play() for the cleaned public schema that repairs common clock/order defects and appends the derived public columns.

Usage

gc_play_by_play_raw(game = 2023030417)

gc_pbp_raw(game = 2023030417)

Arguments

Value

data.frame with one row per event (play)

Examples

gc_raw_Martin_Necas_legacy_game <- gc_play_by_play_raw(game = 2025020275)

Access the GameCenter (GC) play-by-plays for a season

Description

gc_play_by_plays() downloads the cleaned season-level GameCenter parquet snapshot and pads situationCode to the four-character public format.

Usage

gc_play_by_plays(season = 20242025)

gc_pbps(season = 20242025)

Arguments

Value

data.frame with one row per event (play) per game

Examples

# May take >5s, so skip.
gc_pbps_20212022 <- gc_play_by_plays(season = 20212022)

Access the raw GameCenter (GC) play-by-plays for a season

Description

gc_play_by_plays_raw() downloads the stored season-level GameCenter parquet snapshot and returns the raw rows without public-schema cleanup or situation-code padding.

Usage

gc_play_by_plays_raw(season = 20242025)

gc_pbps_raw(season = 20242025)

Arguments

Value

data.frame with one row per raw event (play) per game

Examples

# May take >5s, so skip.
gc_pbps_raw_20212022 <- gc_play_by_plays_raw(season = 20212022)

Access the GameCenter (GC) summary for a game

Description

gc_summary() combines the GameCenter landing and right-rail payloads for one game. The nested list includes the scoreboard, team records, scoring summary, three stars, game videos, officials, season/game identifiers, and related GameCenter metadata when available.

Usage

gc_summary(game = 2023030417)

Arguments

Value

list of various items

Examples

gc_summary_Martin_Necas_legacy_game <- gc_summary(game = 2025020275)

Access all the general managers

Description

general_managers() returns the records-site general-manager registry with one row per general manager and normalized ID/name fields.

Usage

general_managers()

gms()

Value

data.frame with one row per general manager

Examples

all_GMs <- general_managers()

Access the attendance by season and game type

Description

get_attendance() is deprecated. Use attendance() instead.

Usage

get_attendance()

Value

data.frame with one row per season

Access all the award winners/finalists

Description

get_award_winners() is deprecated. Use award_winners() instead.

Usage

get_award_winners()

Value

data.frame with one row per winner/finalist

Access all the awards

Description

get_awards() is deprecated. Use awards() instead.

Usage

get_awards()

Value

data.frame with one row per award

Access the playoff bracket for a season

Description

get_bracket() is deprecated. Use bracket() instead.

Usage

get_bracket(season = season_now())

Arguments

Value

data.frame with one row per series

Access the configurations for team, skater, and goalie reports

Description

get_configuration() is defunct. Use team_report_configurations(), skater_report_configurations(), and/or goalie_report_configurations() instead.

Usage

get_configuration()

Access all the countries

Description

get_countries() is deprecated. Use countries() instead.

Usage

get_countries()

Value

data.frame with one row per country

Access all the draft picks

Description

get_draft_picks() is deprecated. Use draft_picks() instead.

Usage

get_draft_picks()

Value

data.frame with one row per pick

Access the draft rankings for a year and player type

Description

get_draft_rankings() is deprecated. Use draft_rankings() instead.

Usage

get_draft_rankings(year = season_now()%/%10000, player_type = 1)

Arguments

Value

data.frame with one row per player

Access the real-time draft tracker

Description

get_draft_tracker() is deprecated. Use draft_tracker() instead.

Usage

get_draft_tracker()

Value

data.frame with one row per player

Access all the drafts

Description

get_drafts() is deprecated. Use drafts() instead.

Usage

get_drafts()

Value

data.frame with one row per draft

Access the ESPN summary for an athlete (player) and season

Description

get_espn_athlete() is defunct. Use espn_player_summary() instead.

Usage

get_espn_athlete()

Access all the ESPN athletes (players)

Description

get_espn_athletes() is deprecated. Use espn_players() instead.

Usage

get_espn_athletes()

Value

data.frame with one row per ESPN athlete (player)

Access the ESPN statistics for a coach and (multiple) season(s)

Description

get_espn_coach() is defunct. Use coach_career_statistics() instead.

Usage

get_espn_coach()

Access the career ESPN statistics for a coach

Description

get_espn_coach_career() is defunct. Use coach_career_statistics() instead.

Usage

get_espn_coach_career()

Access the ESPN coaches for a season

Description

get_espn_coaches() is defunct. Use coaches() instead.

Usage

get_espn_coaches()

Access the ESPN summary for an event (game)

Description

get_espn_event() is deprecated. Use espn_game_summary() instead.

Usage

get_espn_event(event = 401777460)

Arguments

Value

data.frame with one row per event (game)

Access the ESPN odds for an event (game)

Description

get_espn_event_odds() is deprecated. Use espn_game_odds() instead.

Usage

get_espn_event_odds(event = 401777460)

Arguments

Value

data.frame with one row per provider

Access the officials for an ESPN event (game)

Description

get_espn_event_officials() is defunct. Use gc_summary() and/or wsc_summary() instead.

Usage

get_espn_event_officials()

Access the ESPN play-by-play for an event (game)

Description

get_espn_event_play_by_play() is deprecated. Use espn_play_by_play() instead.

Usage

get_espn_event_play_by_play(event = 401777460)

Arguments

Value

data.frame with one row per play

Access the three stars for an ESPN event (game)

Description

get_espn_event_stars() is defunct. Use gc_summary() and/or wsc_summary() instead.

Usage

get_espn_event_stars()

Access the ESPN events (games) by start and end dates

Description

get_espn_events() is defunct. Use espn_games() instead.

Usage

get_espn_events()

Access the ESPN futures for a season

Description

get_espn_futures() is defunct. Use espn_futures() instead.

Usage

get_espn_futures()

Access the real-time ESPN injury reports

Description

get_espn_injuries() is deprecated. Use espn_injuries() instead.

Usage

get_espn_injuries()

Value

nested data.frame with one row per team (outer) and player (inner)

Access the ESPN summary for a team and season

Description

get_espn_team() is defunct. Use espn_team_summary() instead.

Usage

get_espn_team()

Access all the ESPN teams for a season

Description

get_espn_teams() is defunct. Use espn_teams() instead.

Usage

get_espn_teams()

Access the ESPN transactions by start and end dates

Description

get_espn_transactions() is defunct. Use espn_transactions() instead.

Usage

get_espn_transactions()

Access the statistics for all the franchises by season and game type

Description

get_franchise_season_by_season() is deprecated. Use franchise_season_statistics() instead.

Usage

get_franchise_season_by_season()

Value

data.frame with one row per franchise per season per game type

Access the all-time statistics for all the franchises by team and game type

Description

get_franchise_team_totals() is deprecated. Use franchise_team_statistics() instead.

Usage

get_franchise_team_totals()

Value

data.frame with one row per team per franchise per game type

Access the all-time statistics versus other franchises for all the franchises by game type

Description

get_franchise_vs_franchise() is deprecated. Use franchise_versus_franchise() instead.

Usage

get_franchise_vs_franchise()

Value

data.frame with one row per franchise per franchise per game type

Access all the franchises

Description

get_franchises() is deprecated. Use franchises() instead.

Usage

get_franchises()

Value

data.frame with one row per franchise

Access the boxscore for a game, team, and player type

Description

get_game_boxscore() is deprecated. Use boxscore() instead.

Usage

get_game_boxscore(game = 2023030417, team = "home", player_type = "forwards")

Arguments

Value

data.frame with one row per player

Access the GameCenter (GC) summary for a game

Description

get_game_landing() is deprecated. Use gc_summary() instead.

Usage

get_game_landing(game = 2023030417)

Arguments

Value

list of various items

Access the World Showcase (WSC) summary for a game

Description

get_game_story() is deprecated. Use wsc_summary() instead.

Usage

get_game_story(game = 2023030417)

Arguments

Value

list of various items

Access all the games

Description

get_games() is deprecated. Use games() instead.

Usage

get_games()

Value

data.frame with one row per game

Access the GameCenter (GC) play-by-play for a game

Description

get_gc_play_by_play() is deprecated. Use gc_play_by_play() instead.

Usage

get_gc_play_by_play(game = 2023030417)

Arguments

Value

data.frame with one row per event (play)

Access the glossary

Description

get_glossary() is deprecated. Use glossary() instead.

Usage

get_glossary()

Value

data.frame with one row per terminology

Access the goalie statistics leaders for a season, game type, and category

Description

get_goalie_leaders() is deprecated. Use goalie_leaders() instead.

Usage

get_goalie_leaders(season = "current", game_type = "", category = "wins")

Arguments

Value

data.frame with one row per player

Access the goalies on milestone watch

Description

get_goalie_milestones() is deprecated. Use goalie_milestones() instead.

Usage

get_goalie_milestones()

Value

data.frame with one row per player

Access various reports for all the goalies by season or game

Description

get_goalie_statistics() is defunct. Use goalie_season_report() or goalie_game_report() instead.

Usage

get_goalie_statistics()

Access all the goalies for a range of seasons

Description

get_goalies() is defunct. Use players() instead.

Usage

get_goalies()

Access all the officials

Description

get_officials() is deprecated. Use officials() instead.

Usage

get_officials()

Value

data.frame with one row per official

Access the real-time game odds for a country by partnered bookmaker

Description

get_partner_odds() is deprecated. Use game_odds() instead.

Usage

get_partner_odds(country = "US")

Arguments

Value

data.frame with one row per game

Access the game log for a player, season, and game type

Description

get_player_game_log() is deprecated. Use player_game_log() instead.

Usage

get_player_game_log(player = 8478402, season = "now", game_type = "")

Arguments

Value

data.frame with one row per game

Access the summary for a player

Description

get_player_landing() is deprecated. Use player_summary() instead.

Usage

get_player_landing(player = 8478402)

Arguments

Value

list with various items

Access all the players

Description

get_players() is deprecated. Use players() instead.

Usage

get_players()

Value

data.frame with one row per player

Access the schedule for a date

Description

get_schedule() is deprecated. Use schedule() instead.

Usage

get_schedule(date = "2025-01-01")

Arguments

Value

data.frame with one row per game

Access the scoreboards for a date

Description

get_scoreboards() is deprecated. Use scores() instead.

Usage

get_scoreboards(date = "now")

Arguments

Value

data.frame with one row per game

Access the scores for a date

Description

get_scores() is deprecated. Use scores() instead.

Usage

get_scores(date = "now")

Arguments

Value

data.frame with one row per game

Access the season and game type as of now

Description

get_season_now() is defunct. Use season_now() and/or game_type_now() instead.

Usage

get_season_now()

Access all the seasons

Description

get_seasons() is deprecated. Use seasons() instead.

Usage

get_seasons()

Value

data.frame with one row per season

Access the playoff series for a season and round

Description

get_series() is defunct.

Usage

get_series()

Access the playoff schedule for a season and series

Description

get_series_schedule() is deprecated. Use series_schedule() instead.

Usage

get_series_schedule(season = season_now(), series = "a")

Arguments

Value

data.frame with one row per game

Access the shift charts for a game

Description

get_shift_charts() is deprecated. Use shift_chart() instead.

Usage

get_shift_charts(game = 2023030417)

Arguments

Value

data.frame with one row per shift

Access the skater statistics leaders for a season, game type, and category

Description

get_skater_leaders() is deprecated. Use skater_leaders() instead.

Usage

get_skater_leaders(season = "current", game_type = "", category = "points")

Arguments

Value

data.frame with one row per player

Access the skaters on milestone watch

Description

get_skater_milestones() is deprecated. Use skater_milestones() instead.

Usage

get_skater_milestones()

Value

data.frame with one row per player

Access various reports for all the skaters by season or game

Description

get_skater_statistics() is defunct. Use skater_season_report() or skater_game_report() instead.

Usage

get_skater_statistics()

Access all the skaters for a range of seasons

Description

get_skaters() is defunct. Use players() instead.

Usage

get_skaters()

Access the spotlight players

Description

get_spotlight_players() is deprecated. Use spotlight_players() instead.

Usage

get_spotlight_players()

Value

data.frame with one row per player

Access the standings for a date

Description

get_standings() is deprecated. Use standings() instead.

Usage

get_standings(date = "2025-01-01")

Arguments

Value

data.frame with one row per team

Access the standings rules by season

Description

get_standings_information() is deprecated. Use standings_rules() instead.

Usage

get_standings_information()

Value

data.frame with one row per season

Access all the streams

Description

get_streams() is deprecated. Use streams() instead.

Usage

get_streams()

Value

data.frame with one row per stream

Access the prospects for a team and position

Description

get_team_prospects() is deprecated. Use team_prospects() instead.

Usage

get_team_prospects(team = "NJD", player_type = "forwards")

Arguments

Value

data.frame with one row per player

Access the roster for a team, season, and player type

Description

get_team_roster() is deprecated. Use roster() instead.

Usage

get_team_roster(team = "NJD", season = "current", player_type = "forwards")

Arguments

Value

data.frame with one row per player

Access the roster statistics for a team, season, game type, and player type

Description

get_team_roster_statistics() is deprecated. Use roster_statistics() instead.

Usage

get_team_roster_statistics(
  team = "NJD",
  season = "now",
  game_type = 2,
  player_type = "skaters"
)

Arguments

Value

data.frame with one row per player

Access the schedule for a team and season

Description

get_team_schedule() is deprecated. Use team_season_schedule() instead.

Usage

get_team_schedule(team = "NJD", season = "now")

Arguments

Value

data.frame with one row per game

Access the team scoreboard as of now

Description

get_team_scoreboard() is defunct.

Usage

get_team_scoreboard()

Access the season(s) and game type(s) in which a team played

Description

get_team_seasons() is deprecated. Use team_seasons() instead.

Usage

get_team_seasons(team = "NJD")

Arguments

Value

data.frame with one row per season

Access various reports for all the teams by season or game

Description

get_team_statistics() is defunct. Use team_season_report() and/or team_game_report() instead.

Usage

get_team_statistics()

Access all the teams

Description

get_teams() is deprecated. Use teams() instead.

Usage

get_teams()

Value

data.frame with one row per team

Access the NHL Network TV schedule for a date

Description

get_tv_schedule() is deprecated. Use tv_schedule() instead.

Usage

get_tv_schedule(date = "now")

Arguments

Value

data.frame with one row per program

Access all the venues

Description

get_venues() is deprecated. Use venues() instead.

Usage

get_venues()

Value

data.frame with one row per venue

Access the World Showcase (WSC) play-by-play for a game

Description

get_wsc_play_by_play() is deprecated. Use wsc_play_by_play() instead.

Usage

get_wsc_play_by_play(game = 2023030417)

Arguments

Value

data.frame with one row per event (play)

Access the glossary

Description

glossary() returns NHL glossary terms with one row per term and normalized terminology IDs/names.

Usage

glossary()

Value

data.frame with one row per terminology

Examples

glossary <- glossary()

Access the EDGE 5 vs. 5 statistics for a goalie, season, game type, and category

Description

goalie_edge_five_versus_five() returns goalie EDGE 5-on-5 save-percentage detail for one goalie/season/game type. Use category = 'details' for the full split list or category = 'last 10' for game-level recent form.

Usage

goalie_edge_five_versus_five(
  player = 8476945,
  season = "now",
  game_type = "",
  category = "details"
)

goalie_edge_5_vs_5(
  player = 8476945,
  season = "now",
  game_type = "",
  category = "details"
)

Arguments

Value

list with four items (category = 'details') or data.frame with one row per game (category = 'last 10')

Examples

Mackenzie_Blackwood_L10_5_vs_5_regular_20242025 <- goalie_edge_five_versus_five(
  player    = 8478406,
  season    = 20242025,
  game_type = 2,
  category  = 'L'
 )

Access the goalie EDGE statistics leaders for a season and game type

Description

goalie_edge_leaders() returns the goalie EDGE landing-page leader groups for one season and game type, such as save percentage, 5-on-5 save percentage, and shot-location leader blocks.

Usage

goalie_edge_leaders(season = "now", game_type = "")

Arguments

Value

list of various items

Examples

goalie_EDGE_leaders_regular_20242025 <- goalie_edge_leaders(
  season    = 20242025,
  game_type = 2
)

Access the EDGE save percentage statistics for a goalie, season, game type, and category

Description

goalie_edge_save_percentage() returns a goalie's EDGE save-percentage detail list, or recent game rows when category = 'last 10'.

Usage

goalie_edge_save_percentage(
  player = 8476945,
  season = "now",
  game_type = "",
  category = "details"
)

Arguments

Value

list with two items (category = 'details') or data.frame with one row per game (category = 'last 10')

Examples

Mackenzie_Blackwood_L10_sP_regular_20242025 <- 
  goalie_edge_save_percentage(
    player    = 8478406,
    season    = 20242025,
    game_type = 2,
    category  = 'L'
  )

Access the season(s) and game type(s) in which there exists goalie EDGE statistics

Description

goalie_edge_seasons() returns the seasons and game type IDs for which the NHL EDGE goalie endpoints expose data.

Usage

goalie_edge_seasons()

Value

data.frame with one row per season

Examples

goalie_EDGE_seasons <- goalie_edge_seasons()

Access the EDGE shot location statistics for a goalie, season, game type, and category

Description

goalie_edge_shot_location() returns a goalie's EDGE save results by shot location, either as detailed splits or shot-location totals.

Usage

goalie_edge_shot_location(
  player = 8476945,
  season = "now",
  game_type = "",
  category = "details"
)

Arguments

Value

data.frame with one row per shot location

Examples

Mackenzie_Blackwood_shot_location_totals_regular_20242025 <- 
  goalie_edge_shot_location(
    player    = 8478406,
    season    = 20242025,
    game_type = 2,
    category  = 'T'
  )

Access the EDGE summary for a goalie, season, and game type

Description

goalie_edge_summary() returns the full NHL EDGE detail payload for one goalie, season, and game type, including goalie metadata and the available save-percentage and shot-location summary blocks.

Usage

goalie_edge_summary(player = 8476945, season = "now", game_type = "")

Arguments

Value

list of various items

Examples

Mackenzie_Blackwood_EDGE_summary_regular_20242025 <- goalie_edge_summary(
  player    = 8478406, 
  season    = 20242025,
  game_type = 2
)

Access various reports for a season, game type, and category for all the goalies by game

Description

goalie_game_report() returns the game-level version of a selected goalie stats report, with one row per goalie per game and category-specific metrics.

Usage

goalie_game_report(
  season = season_now(),
  game_type = game_type_now(),
  category = "summary"
)

Arguments

Value

data.frame with one row per game per goalie

Examples

# May take >5s, so skip.
advanced_goalie_game_report_playoffs_20212022 <- 
  goalie_game_report(
    season    = 20212022, 
    game_type = 3, 
    category  = 'advanced'
  )

Access the scoring statistics for all the goalies by game

Description

goalie_game_scoring() returns records-site goalie scoring rows by player and game.

Usage

goalie_game_scoring()

Value

data.frame with one row per player per game

Examples

goalie_game_scoring <- goalie_game_scoring()

Access the statistics for all the goalies by game

Description

goalie_game_statistics() returns records-site goalie stat rows by player and game, including opponent fields and normalized team abbreviations.

Usage

goalie_game_statistics()

goalie_game_stats()

Value

data.frame with one row per goalie per game

Examples

goalie_game_stats <- goalie_game_statistics()

Access the goalie statistics leaders for a season, game type, and category

Description

goalie_leaders() returns the NHL.com leaders table for one goalie category, season, and game type, with normalized player and team fields.

Usage

goalie_leaders(season = "current", game_type = "", category = "wins")

Arguments

Value

data.frame with one row per player

Examples

GAA_leaders_regular_20242025 <- goalie_leaders(
  season    = 20242025,
  game_type = 2,
  category  = 'GAA'
)

Access the goalies on milestone watch

Description

goalie_milestones() returns NHL.com goalie milestone-watch rows, including goalie/team identifiers and the milestone/countdown fields exposed by the endpoint.

Usage

goalie_milestones()

Value

data.frame with one row per player

Examples

goalie_milestones <- goalie_milestones()

Access the career regular season statistics for all the goalies

Description

goalie_regular_statistics() returns records-site regular-season career goalie totals, with one row per goalie.

Usage

goalie_regular_statistics()

goalie_regular_stats()

Value

data.frame with one row per goalie

Examples

goalie_career_regular_statistics <- goalie_regular_statistics()

Access the configurations for goalie reports

Description

goalie_report_configurations() returns the goalie-report configuration block from the stats API, including valid report categories, fields, filters, and split options accepted by goalie_season_report() and goalie_game_report().

Usage

goalie_report_configurations()

goalie_report_configs()

Value

list with various items

Examples

goalie_report_configs <- goalie_report_configurations()

Access the career scoring statistics for all the goalies

Description

goalie_scoring() returns records-site career scoring totals for goalies, with one row per goalie.

Usage

goalie_scoring()

Value

data.frame with one row per player

Examples

goalie_scoring <- goalie_scoring()

Access various reports for a season, game type, and category for all the goalies by season

Description

goalie_season_report() returns a season-level goalie report for a selected stats category, with one row per goalie and the metric columns defined by that category.

Usage

goalie_season_report(
  season = season_now(),
  game_type = game_type_now(),
  category = "summary"
)

Arguments

Value

data.frame with one row per player

Examples

# May take >5s, so skip.
advanced_goalie_season_report_playoffs_20212022 <- 
  goalie_season_report(
    season    = 20212022, 
    game_type = 3, 
    category  = 'advanced'
  )

Access the statistics for all the goalies by season, game type, and team.

Description

goalie_season_statistics() returns records-site goalie stat rows by player, team, season, and game type, preserving separate rows when a goalie changed teams.

Usage

goalie_season_statistics()

goalie_season_stats()

Value

data.frame with one row per player per season per game type, separated by team if applicable

Examples

goalie_season_stats <- goalie_season_statistics()

Access the playoff statistics for all the goalies by series

Description

goalie_series_statistics() returns records-site playoff goalie totals by player and playoff series.

Usage

goalie_series_statistics()

goalie_series_stats()

Value

data.frame with one row per player per series

Examples

goalie_series_stats <- goalie_series_statistics()

Access the career statistics for all the goalies

Description

goalie_statistics() returns records-site regular-season plus playoff career goalie totals, with one row per goalie.

Usage

goalie_statistics()

goalie_stats()

Value

data.frame with one row per player

Examples

goalie_stats <- goalie_statistics()

Save an Instagram (IG) shareable cumulative expected goals (xG) plot

Description

ig_game_cumulative_expected_goals() fetches one GameCenter play-by-play, scores shot attempts with calculate_expected_goals(), and renders a home/away cumulative xG time series on a 1080-by-566-style PNG canvas.

Usage

ig_game_cumulative_expected_goals(game = 2023030417, model = NULL, save = TRUE)

ig_game_cum_xG(game = 2023030417, model = NULL)

Arguments

Value

NULL, invisibly

Examples

# May take >5s, so skip.
ig_game_cumulative_expected_goals(
  game  = 2023030417,
  save  = FALSE
)

Save an Instagram (IG) shareable shot-location plot for a game

Description

ig_game_shot_locations() fetches one GameCenter play-by-play, scores its shot attempts with calculate_expected_goals(), filters to the selected home or away team, and renders a 1080-by-566-style PNG shot map. Points are jittered for readability, shaped by event result, and colored by capped xG.

Usage

ig_game_shot_locations(
  game = 2023030417,
  team = "home",
  model = NULL,
  save = TRUE
)

ig_game_shot_locs(game = 2023030417, team = "home", model = NULL)

Arguments

Value

NULL, invisibly

Examples

# May take >5s, so skip.
ig_game_shot_locations(
  game  = 2023030417,
  team  = 'H',
  save  = FALSE
)

Access the location for a zip code

Description

location() returns the NHL postal lookup result for one ZIP/postal code, including country, region, and related local-market fields when available.

Usage

location(zip = 10001)

Arguments

Value

data.frame with one row per team

Examples

Cranbrook_Schools <- location(48304)

Access the draft lottery odds

Description

lottery_odds() returns historical draft-lottery odds and outcomes by draft year and lottery slot.

Usage

lottery_odds()

Value

data.frame with one row per draft lottery

Examples

lottery_odds <- lottery_odds()

Access all the officials

Description

officials() returns the records-site official registry with one row per official and normalized official ID, name, and referee-association fields.

Usage

officials()

Value

data.frame with one row per official

Examples

all_officials <- officials()

Access all the penalty shots

Description

penalty_shots() returns historical penalty-shot records with one row per attempt, including game, season/game type, shooter/goalie, team, and outcome fields.

Usage

penalty_shots()

pss()

Value

data.frame with one row per penalty shot

Examples

all_pss <- penalty_shots()

Ping

Description

ping() is defunct.

Usage

ping()

Access the game log for a player, season, and game type

Description

player_game_log() returns one player's GameCenter game log for a season and game type, with one row per game and normalized opponent, score/result, and player stat fields.

Usage

player_game_log(player = 8478402, season = "now", game_type = "")

Arguments

Value

data.frame with one row per game

Examples

Martin_Necas_game_log_regular_20242025 <- player_game_log(
  player    = 8480039,
  season    = 20242025,
  game_type = 2
)

Access the season(s) and game type(s) in which a player played

Description

player_seasons() returns the seasons and game type IDs available in a player's GameCenter game-log payload.

Usage

player_seasons(player = 8478402)

Arguments

Value

data.frame with one row per season

Examples

Martin_Necas_seasons <- player_seasons(player = 8480039)

Access the summary for a player

Description

player_summary() returns the public player landing payload for one player, including bio/team fields, current season stats, career totals, season totals, awards, and featured media when available.

Usage

player_summary(player = 8478402)

Arguments

Value

list with various items

Examples

Martin_Necas_summary <- player_summary(player = 8480039)

Access all the players

Description

players() returns the records-site player registry with one row per player and normalized IDs, names, position, handedness, and birth fields.

Usage

players()

Value

data.frame with one row per player

Examples

# May take >5s, so skip.
all_players <- players()

Access the playoff statistics by season

Description

playoff_season_statistics() returns league-wide playoff totals by season, including games, goals, and related year-level totals.

Usage

playoff_season_statistics()

playoff_season_stats()

Value

data.frame with one row per season

Examples

playoff_season_stats <- playoff_season_statistics()

Access all the penalty shots

Description

ps() is deprecated. Use penalty_shots() instead.

Usage

ps()

Value

data.frame with one row per penalty shot

Access the replay for an event

Description

replay() downloads NHL puck/player tracking sprite data for one goal event and returns one row per decisecond with puck coordinates plus dynamic ⁠playerN*⁠ columns for tracked skaters.

Usage

replay(game = 2023030417, event = 866)

Arguments

Value

data.frame with one row per decisecond

Examples

Gabriel_Landeskog_first_regular_goal_back_replay <- replay(
  game  = 2025020262,
  event = 751
)