fastRhockey 1.1.0
Breaking changes
These change the shape or type of output that CRAN 1.0.0 returned. Code that upgrades from 1.0.0 may need to change.
-
espn_nhl_team_schedule():home_scoreandaway_scoreare now always character, as documented. A fully played season used to return them as double (#84). -
ahl_schedule(),ohl_schedule(),whl_schedule()andqmjhl_schedule()now return every column as character, andgame_statuscarries the schedule view’s strings (Final OTwhere 1.0.0 returnedFinal 1st OT) (#74). -
pwhl_pbp()and the AHL / OHL / WHL / QMJHL*_pbp()functions: the derived coordinates are now rotations of the feet frame.x_coord_fixed/y_coord_fixedhave the home team shooting right,x_coord_right/y_coord_righthave every team shooting right, andx_coord_vertical/y_coord_verticalhave every team shooting up. The right and vertical columns areNAwhen an event’s side is unknown. See the bug fix below for the details (#75).
New features
- European hockey and ESPN college hockey (453 wrappers), at parity with sportsdataverse-py. Seasons are END years (2027 = 2026-27). Every request waits at least one second after the last one to the same host, 429/500/502/ 503/504 answers are retried honouring
Retry-After(capped at 120 s), and failures raise classed conditions:fastRhockey_no_data(the provider has nothing for the request),fastRhockey_asset_fetch(the answer is unknown: a 403/5xx, a block, an empty body, a body for another game) andfastRhockey_bad_request, all inheritingfastRhockey_error. Results arefastRhockey_data;return_parsed = FALSEreturns the raw payload (#83).- eSports (DEL, ICE Hockey League, EIHL, Metal Ligaen): 41 wrappers,
del_*(12),icehl_*(12),eihl_*(9),metal_*(8). - KHL: 23
khl_*wrappers over khl.ru and the webcaster API. - SHL: 29
shl_*wrappers, includingshl_ssgt_uuid()andshl_player_crosswalk(). - Liiga: 23
liiga_*wrappers. - SIHF (Swiss Ice Hockey Federation, data.sihf.ch): 33
sihf_*wrappers. - Czech Extraliga: 9
elh_*wrappers. - HockeyAllsvenskan: 11
ha_*wrappers. - Swiss National League (nationalleague.ch): 17
nl_*wrappers. The site’s robots.txt disallows/api, so use these functions sparingly: requests are spaced at least 1 s apart, and they suit interactive, incremental access rather than bulk backfills or public mirrors. - Ligue Magnus: 11
magnus_*wrappers. - VHL (Russia): 13
vhl_*wrappers plusvhl_tn(). - ESPN men’s and women’s college hockey: 242 wrappers, 121 per league (
espn_mch_*andespn_wch_*).
- eSports (DEL, ICE Hockey League, EIHL, Metal Ligaen): 41 wrappers,
- Deliberate differences from sportsdataverse-py: R has no 64-bit integer, so ids past 2^31 (SIHF
game_id, National Leaguegame_idand unix times, eSports epoch-millisecond timestamps, KHL webcaster*_ts, Czech Extraligasort_order) are doubles, andreturn_as_pandasand**kwargsare dropped (#83). -
load_nhl_groups(),load_nhl_group_seasons(),load_nhl_group_aliases()andload_nhl_team_group_seasons()— season-by-season conference and division reference tables from thenhl_groupssportsdataverse-data release: each group’s name and parent as of every season, every source’s ids and names for it, and each team’s conference and division by season (1918+, keyed by the season’s end year) (#70). - ESPN college hockey follow-ups: the
espn_mch_*/espn_wch_*wrappers take the sportsdataverse-py arguments the shared helpers used to drop (scoreboardweek,season_type,groups,limit; standingsgroup,standings_type; leaderssort; coach_recordrecord_type;limiton teams_site, team_roster, transactions and season_awards);espn_nhl_*requests are unchanged. Newespn_{mch,wch}_{pbp,team_box,player_box}wrappers mirror the NHL ones. The college@returntables are now checked against captured mch/wch bodies (30 verified; injuries, transactions and rosters were empty in every capture and say so) (#84). - VHL: requests use the shared polite retry (429/5xx with
Retry-After) and HTML tables parse about 6x faster (a stats page 24.7 s -> 4.0 s) (#84). - Documentation: a data status section and navbar link (#71), the HockeyTech raw-coordinate canvas documented (#73), the newer SportsDataverse packages in the site’s SDV menu (#77), BibTeX spelled correctly (#78), and a star history chart in the README (#86). The pkgdown articles moved onto the shared SportsDataverse article template (#67), the site gained Plausible analytics and a trimmed search index (#68), and the README and site link the package cheat sheet and cite the current release year.
- Testing and CI: live tests now always skip on CRAN and CI and run only when their
RUN_*_TESTStoggle is1ortrue; an unset toggle skips. CI adds an R-devel check job, a urlchecker job and a test-coverage job (#88).
Bug fixes
NHL
x_fixed/y_fixedrotate the rink byhomeTeamDefendingSide(home shoots right;(x, y) -> (-x, -y)when the home team defends the right end) instead ofx_fixed = abs(x)for home events and-abs(x)for away. The old form mirrored every attempt from the shooter’s own half into the attacking zone, so a 159 ft shot was measured at 20 ft (and scored as a high-danger chance), and flippedyon the sign ofx. Plays without a side use the period’s, then where each team’s shots cluster.shot_distance/shot_anglefor aBLOCKED_SHOT(whose event team is the blocker) are measured to the shooter’s target net.The NHL xG models are no longer downloaded in
.onLoad(), which CRAN policy forbids:library(fastRhockey)makes no network call, andhelper_nhl_calculate_xg()(and sonhl_game_pbp()/nhl_game_feed()) loads them on first use. They now come from the sportsdataverse-datanhl_xg_modelsrelease that sportsdataverse-py reads, checked against the sha256s in the release’s manifest (xg_model_meta.json, written by fastRhockey-nhl-data’s publisher) rather than hashes pinned in this package: a cached copy that matches is used (offline too, with the last manifest seen), one that does not (another training) is replaced, so a retrain reaches installed copies without a fastRhockey release: the first load that fetches the new manifest replaces the cached boosters (offline, the last manifest seen keeps validating the copies it named). A refresh commits only a complete, verified set, so one that fails part-way leaves the previous set usable.refresh_xg_models()still clears and re-fetches them (#96).The PHF games index csv (
update_phf_db()) is read through.release_csv_from_url(), the release-read helper the loaders use (150 s timeout floor, two retries, a warning naming the url), instead ofutils::read.csv(url())with no retry.data.tablefloor raised to 1.15.0 forfread(file = url).update_nhl_db(),update_pwhl_db()and the PHF builder no longer drop the play-by-play table on a bad games-index read.force_rebuild = TRUEreads the index, drops the table and reloads only the seasons the index lists, so a failed, empty or partial index read used to lose seasons from the database. The builder now aborts, naming the index url, and leaves the table untouched. Release csvs are downloaded with libcurl to a temporary file beforefread()reads it (withdownload.file.method = "curl",fread(url)shelled out to curl, which ignores HTTP errors and R’stimeout), and the games-index read treats anfread()warning (a read that stopped early) as an error, without retrying it.ahl_pbp(),ohl_pbp(),whl_pbp(),qmjhl_pbp()and the four*_game_corsi()functions: a game with no events failed with “replacement has 1 row, data has 0”. They now return an empty data frame.The nine deprecated NHL Edge top-10 functions (
nhl_edge_goalie_5v5_top_10()and friends) no longer send a request to the removed endpoint. They warn and returnNULL.The
espn_mch_coach(),espn_mch_coach_record(),espn_wch_coach()andespn_wch_coach_record()examples called functions that do not exist. They now useespn_mch_season_coaches()/espn_wch_season_coaches().nhl_game_pbp()/nhl_game_feed(): the shiftCHANGErows hadgame_id = NA(465 of 789 rows in game 2025021229), because the shift rows were padded withNAfor every play-by-play column. Grouping or filtering bygame_iddropped every shift.game_idis now set on every row.helper_nhl_calculate_xg()joined the xG predictions back byevent_id, which restarts at 0 in every game, so a frame of two or more games got extra rows (two 2025-26 games: 1,540 rows in, 1,554 out) and shots took xG from the wrong game. It now joins bygame_idandevent_idand keeps the input row order. Given a frame that already hasxg(asnhl_game_pbp()output does), it now replaces that column instead of returningxg.x/xg.y.helper_nhl_calculate_xg()stopped with an error whenxgboostwas not installed, though?nhl_xgsays xG comes backNA. It now warns (classfastRhockey_no_xgboost, once per session) and returnspbpwithxg = NA.nhl_game_pbp()/nhl_game_feed()pass that warning on.SHL:
www.shl.se’sstatistics-v2/layout-inforenamed its season directory fromseasonSeriesGameTypeTeamstooriginalSeasonSeriesGameTypeTeams, so every SHL lookup (andshl_last_game_day()) stopped with “no ssgt directory in the body”. The SHL functions read the new key and fall back to the old one (#90).pwhl_standings()ignoredseasonandregularand always returned 2023-24. It now resolves the HockeyTech season id from them, and its default ismost_recent_pwhl_season()(#90).The PWHL season-id fallback table, used when the HockeyTech season list cannot be read, now runs through 2026-27, and the AHL / OHL / WHL / QMJHL most-recent-season fallback is computed from the date instead of a fixed 2026 (#90).
nhl_stats_skaters(),nhl_stats_goalies(),nhl_stats_teams()andnhl_playoff_carousel()asked for the next season ("20272028"in November 2026); they now default tomost_recent_nhl_season_api_param()(#90).The PWHL and NHL release loaders called with their default season now load the newest published season, with a message, when the current one has no file yet (every
load_pwhl_*()returned an empty table from 1 November until the first 2026-27 game). An explicit request for an unpublished season still returns an empty table, and a season outside the published range is a cli error (#90).The European hockey per-host throttle stamped each request at its scheduled time, not when its wait actually ended, so an oversleeping
Sys.sleep()(macOS timer coalescing on a loaded machine) let the next request to that host go out early, inside the one-second spacing. The clock now records the real wake time (#87).khl_player_stats(position = "goalies")returned 20 goalies who had not played (khl.ru orders goalies by goals-against average ascending and ignores sort fields). It now fetches every page (the count fromnav.max) and returns one list sorted by games played, then wins, then name, as sportsdataverse-py does;pageis ignored for goalies. A partial list (a missing page, a row count that does not fit the page count, a player on two pages, more than 30 pages) raisesfastRhockey_asset_fetch. The goalie columns (w,l,sop,ga,sv,sv_pct,gaa,so,toi) are now documented and typed as in sportsdataverse-py:sv_pctis on a 0-100 scale (92.2),gaais double,toiis mm:ss text with"-"asNA. Skaters are unchanged (#85).ESPN college hockey routes match sportsdataverse-py:
coach_recordasks forcoaches/{id}/record/{record_type}(default0) andcoach_seasonforcoaches/{id}/seasons/{season}.calendardeliberately keeps reading the scoreboard payload: sportsdataverse-py’s/calendarroute answers 404 for both college leagues (#84).ESPN scoreboards (
espn_nhl_scoreboard()and the college ones): thebroadcastcolumn joins every network name with “,” (“ESPNU, ESPN+”; feed order, deduped), exactly as sportsdataverse-py; it used to carry ESPN’s “/”-joined first-market string. Team schedules use the same rule (#84).ESPN
teams_site,team_scheduleandstandingsreturned empty frames on college bodies (noalternateColor; played and unplayed games mixing score types, which also hit NHL schedules spanning both; a standings table at the root of the body) (#84).espn_nhl_team_schedule()scores are now always character (see Breaking changes).ESPN college
limitarguments now default as in sportsdataverse-py (scoreboard,team_rosterandtransactions500,teams_site1000,season_awards200), so R and Python fetch the same page; NHL requests are unchanged (#84).KHL: when khl.ru answers session priming with its ServicePipe anti-bot challenge page, the error now says so (“khl.ru served an anti-bot challenge page; try again later or through
getOption('fastRhockey.proxy')”) instead of reporting a missingsessid(#84).The NHL release loaders rejected the 2009-10 season: every
load_nhl_*()release loader (and.nhl_release_loader()’s default) requiredseasons >= 2011, but each sportsdataverse-data release publishes from 2010. They now accept 2010, matching sportsdataverse-py (sportsdataverse/sportsdataverse-py#765) (#79). Two of those 2009-10 files are thinner at the source:load_nhl_pbp()comes from a lighter feed (53 columns, not 92), andload_nhl_three_stars()covers 324 of 1,318 games.load_nhl_pbp_lite()’splay_by_play_lite_<year>files started at 2024 until the release was backfilled for 2010-2023 (2026-10-11), so earlier lite seasons used to download nothing.load_nhl_game_rosters()documents all twelve of its columns (#79).shot_distance/shot_angle(andscoring_chance) of an empty-net goal from a team’s own half were measured to the nearer net: 59 ft for a median 126-ft goal (27 such goals in 320 PWHL games). Empty-net goals are now measured to the net their team attacks. Every other event keeps the nearer net: per-event validation showed own-half events with a goalie in net are near-net events whose coordinates the feed mirrored (#76).The derived play-by-play coordinates of
pwhl_pbp()and the AHL / OHL / WHL / QMJHL*_pbp()functions put home-team events off the rink: the home flip applied a 0-200 x 0-85 mirror to coordinates already in centre-origin feet, so homex_coord_rightran 191 to 290 ft (PWHL game 42). The feed puts the home team’s attack toward x = 0 in every period (320 PWHL games), and the columns are now rotations of the feet frame:x_coord_fixed/y_coord_fixed= (-x, -y), home team shooting right (the NHLx_fixedconvention);x_coord_right/y_coord_right= home (-x, -y), visitor (x, y);x_coord_vertical/y_coord_vertical= (-y_right, x_right). The right and vertical columns areNAwhen an event’s side is unknown (no team, as on faceoffs, or no home team id) instead of being treated as the visitor’s.x_coord,y_coord,shot_distanceandshot_angleare unchanged (#75).ahl_schedule(),ohl_schedule(),whl_schedule()andqmjhl_schedule()returned other seasons’ games. They read HockeyTech’smodulekit/scorebar, which ignores theseason_idit is sent, returns games oldest first and stops at 10,000 rows, soahl_schedule(season = 2026)returned AHL games from 1995 to 2012 and none from 2025-26. They now readmodulekit/schedule, which the feed scopes to one season (live 2026-10-08: AHL 2025-26 = 1,152 games, OHL 682, WHL 782, QMJHL 578), and drop any row from another season. With neitherseasonnorseason_idthey return the newest regular season.game_statusnow carries the schedule view’s strings (Final OTwhere the scorebar saidFinal 1st OT), and every column is character (#74).The AHL, OHL, WHL and QMJHL functions that take
season =(schedule, standings, teams, rosters, leaders, …) could resolve it to the wrong HockeyTech season.ahl_schedule(season = 2026)resolved to the “2026 All-Star Challenge”, which the feed lists ahead of the 2025-26 regular season, and the WHL’s “2025 - 26” season names read as 2025, sowhl_schedule(season = 2026)returned 2026-27. Season names now read as their end year the way sportsdataverse-py reads them (spaced and slashed spans,YY-ZZ, compactYYZZ, a one-year preseason that opens the next season), one-off events are skipped for regular-season and playoff lookups, and the newest season counts only real regular seasons. On the 20 leagues’ real seasons captures, R and sportsdataverse-py now agree on all 485 seasons’ end year and type (#74).nhl_teams(season =)stopped with “missing value where TRUE/FALSE needed” (reported as “Error fetching teams”) instead of returningNULLwith “No team data found” when the NHL API has no standings for the date it asks for: the API then returns an empty list, whosenrow()isNULL. It also now says thatseasonis the year the season starts in (2024 for 2024-25), which is what it queries (January ofseason + 1), whilemost_recent_nhl_season()returns the year the season ends (#69).tail()works on the result of every loader and every function that returns afastRhockey_datatibble. The class vector they set, in the loaders and inmake_fastRhockey_data(), still listeddata.table, sotail()failed with “Can’t subset columns past the end” (the bug fixed in hoopR as hoopR#88). The class is nowfastRhockey_data/tbl_df/tbl/data.frame.A slow release download no longer drops a season from a multi-season load. The
.rdsand group.csvreads behind every release-backedload_*()loader raise the download timeout to at least 150 seconds (a largeroptions(timeout)is kept, and the option is restored afterwards) and retry a failed download twice. A 404 is not retried. If a file still fails, the warning names its URL and says the result is incomplete; the seasons that loaded are still returned.nhl_teams_stats(),nhl_player_stats(),nhl_game_content()andpwhl_player_box()returnNULLwith a message when the request fails, andpwhl_standings()when the response can’t be parsed, as the other NHL and PWHL wrappers do. They used to stop with “object ‘…’ not found”.espn_nhl_draft()returns ESPN’s draft board, one row per pick (year,overall,round,pick,status,tradedand the team holding the pick). It read anitemslist the endpoint does not send, so it always returned an empty tibble.fox_nhl_odds()finds the six-pack odds in thesectionListmodules, where Fox now sends them; it returned an empty tibble for every game.update_nhl_db()andupdate_pwhl_db()no longer need dbplyr, which is not a dependency: the stored game ids are read with a plainDBIquery.nhl_teams(),nhl_standings(),nhl_schedule(),nhl_draft(),nhl_draft_year(),nhl_draft_prospects(),nhl_draft_prospects_info()and the HTML fallback ofnhl_game_shifts()fetch through the package’s request layer, so they get the same retries, timeout andfastRhockey.proxyoption as the other NHL wrappers.The
pwhl_player_box()failure message points topwhl_schedule(), not the defunctphf_schedule().
Tests
- Recorded API responses replay offline, so the NHL, ESPN NHL, Fox, PWHL and AHL / OHL / WHL / QMJHL wrappers are tested on CI without the network (
data-raw/http_fixtures/records them; the fixtures are not in the package tarball, and those tests skip when they are missing). The defunct PHF code is left out of the coverage figure (.covrignore).
Dependencies
-
xml2 (>= 1.3)andstatsmoved from Suggests to Imports andutilsis now listed in Imports (#83); thetestthatfloor is raised to 3.1.7 (#74). -
RcppandRcppParallelare no longer Imports (fastRhockey has no compiled code), and furrr, future, ggplot2, ggrepel, rmarkdown, stringi and usethis are no longer in Suggests: nothing used them (#90).
Documentation
- The DESCRIPTION title and description now cover every family the package wraps (NHL, PWHL, the CHL and AHL leagues, ESPN and Fox, the European leagues and college hockey), and the help pages are plain ASCII (#90).
- Network examples whose hosts are slow from automated environments now run only interactively (
@examplesIf interactive()):ha_games(),liiga_teams(),nhl_records_draft_prospect(),espn_nhl_standings_core(),load_nhl_pbp(),load_nhl_pbp_full()and nine VHL functions (vhl_schedule(),vhl_game_info(),vhl_goals(),vhl_penalties(),vhl_player_box(),vhl_goalie_box(),vhl_pbp(),vhl_skater_stats(),vhl_goalie_stats()). The functions are unchanged. - The DESCRIPTION title no longer starts with “Functions to”, and the description spells out each league acronym and quotes the API and service names.
- The 17
nl_*()examples run only interactively, because nationalleague.ch’s robots.txt disallows/api. Five more examples that took over 5 s of CPU also run only interactively:icehl_league_part_player_stats(),icehl_schedule(),espn_nhl_player_splits(),espn_nhl_standings()andha_schedule(). - The
espn_mch_player_vs_player()andespn_wch_player_vs_player()examples passopp_id, the argument’s actual name. - The
elh_scoreboard()example uses a fixed past date with games instead of yesterday’s date. - The defunct
phf_*()andload_phf_*()functions no longer carry examples, which could only raise the defunct error. - The internal play-by-play helpers in
nhl_game_feed.Rare no longer rendered as help pages. - Each
espn_wch_*()function now shares its help page with the matchingespn_mch_*()function (same arguments, same columns), so the 121 pairs take 121 help pages instead of 242.?espn_wch_scoreboardstill works. - The help pages of the seven largest families (ESPN NHL, ESPN MCH / WCH, SIHF, SHL, KHL, Liiga, National League) no longer list every other member of the family under “See also”; those lists grew with the square of the family size and made up most of the installed help. Each page links to one family index page instead (
?family_espn_nhl,?family_espn_mch,?family_sihf,?family_shl,?family_khl,?family_liiga,?family_national_league). With the change above, the installed size drops from 8.9 MB to 6.0 MB.
fastRhockey 1.0.0
CRAN release: 2026-08-25
Breaking Changes
- Version 1.0.0 signals API stability for NHL and PWHL endpoints.
- All PHF functions are formally deprecated via
lifecycle. The Premier Hockey Federation ceased operations; use PWHL functions instead. Functions will be removed in a future release. - Consolidated new NHL API functions into existing NHL function names rather than creating
_v2variants, since the original API endpoints were deprecated by the NHL. This meansnhl_game_feed(),nhl_game_boxscore(),nhl_schedule(),nhl_teams(),nhl_teams_roster(), andnhl_player_info()now use the newapi-web.nhle.comendpoints directly.
New PWHL Functions
-
pwhl_pbp()– PWHL play-by-play data. -
pwhl_player_box()– PWHL player box scores (skaters and goalies). -
pwhl_game_info()– PWHL game information and metadata. -
pwhl_game_summary()– Detailed game summary (scoring, penalties, shots by period, three stars). -
pwhl_standings()– PWHL league standings. -
pwhl_stats()– PWHL stat leaders (skaters and goalies). -
pwhl_leaders()– League leaders (top scorers and top goalies). -
pwhl_season_id()– PWHL season ID lookup (now API-driven with fallback). -
pwhl_player_info()– Player biographical and profile information. -
pwhl_player_game_log()– Per-game statistics for a player in a season. -
pwhl_player_stats()– Career and season-by-season statistics for a player. -
pwhl_player_search()– Search for players by name. -
pwhl_transactions()– Player transactions for a season. -
pwhl_streaks()– Player streak data for a season. -
pwhl_playoff_bracket()– Playoff bracket / series data. -
pwhl_scorebar()– Recent and upcoming game scores. -
most_recent_pwhl_season()– Utility to get the current PWHL season year. -
load_pwhl_pbp()– Load pre-scraped PWHL play-by-play data. -
load_pwhl_player_box()– Load pre-scraped PWHL player box scores. -
load_pwhl_schedule()– Load pre-scraped PWHL schedules. -
load_pwhl_rosters()– Load pre-scraped PWHL team rosters. -
update_pwhl_db()– Update or create a PWHL play-by-play database. -
load_pwhl_shifts()andload_pwhl_xg_pbp()— loaders for the two published PWHL release datasets that had no R access (per-player shift charts and xG-enriched play-by-play), completing coverage of every hockey tag on the sportsdataverse-data releases.
New NHL Functions
-
nhl_where_to_watch()– streaming/broadcast availability. -
nhl_partner_game_odds()– partner game odds by country. - NHL API migration to
api-web.nhle.com:nhl_game_feed(),nhl_game_boxscore(),nhl_schedule(),nhl_teams(),nhl_teams_roster(),nhl_player_info(),nhl_player_game_log(),nhl_stats_goalies(),nhl_stats_skaters(),nhl_stats_teams(),nhl_stats_misc(),nhl_gamecenter_landing(),nhl_gamecenter_right_rail(),nhl_scoreboard(),nhl_scores(),nhl_seasons(),nhl_tv_schedule(),nhl_game_story(),nhl_game_content(),nhl_game_shifts(),nhl_playoff_bracket(),nhl_playoff_schedule(),nhl_playoff_carousel(). - xG model integration via
helper_nhl_calculate_xg(). -
nhl_game_shifts()gains adetailedargument:detailed = TRUEreturns the per-player shift records (one row per player-shift with game-second on/off times) instead of the aggregated one-row-per-change frame (#26).
Bug Fixes
- Fixed
nhl_draft_year()– NHL API removed the/v1/draft/picks/{year}endpoint. The function now iterates over rounds 1-7 using/v1/draft/picks/{year}/{round}. - Fixed
pwhl_stats()– resolved “object ‘players’ not found” error when API calls failed. Fixed team ID resolution for skater stats. - Fixed
pwhl_schedule()– theseasoncolumn was inadvertently dropped from the output. It is now included. - Fixed
refresh_xg_models()– resolved “cannot change value of locked binding” error by storing xG models in a package environment (.xg_env) instead of top-level bindings. - Fixed NAMESPACE: removed
import(tidyverse)which violated CRAN policy. Individual packages (dplyr, tidyr, etc.) are already imported. -
pwhl_stats()now resolves theseasonargument to the correct HockeyTech season id instead of always returning the inaugural 2024 season (#50), and theteamfilter works for both positions and accepts a team code ("OTT"), label ("Ottawa"), or full name — an unknown team now errors informatively instead of silently returning the whole league (#49). -
pwhl_stats(),pwhl_schedule(), andpwhl_standings()now strip the HockeyTech JSONP envelope through the shared.hockeytech_api()helper instead of per-function regexes that broke on payload-shape changes (empty results for 2025 onward). -
pwhl_stats()skater results are resilient to the shootout stat block dropping out of the feed (absent after the inaugural season). -
Fix:
pwhl_playoff_bracket()errored with$ operator is invalid for atomic vectorsand returnedNULL. The HockeyTech feed returnsteam1/team2as bare id strings (not nested objects) with wins in siblingteam1_wins/team2_winsfields; the parser now reads these correctly. -
nhl_stats_players()now detectsdata: []empty-list responses (the API returns this when nocayenne_expfilter is supplied) and returnsNULLwith a friendly hint instead of crashingclean_names(). -
nhl_stats_skater_leaders()andnhl_stats_goalie_leaders()no longer passstart/limitquery parameters, which theleaders/{skaters,goalies}/{attribute}endpoint rejects with a 500 Cayenne SQL error. Roxygen now documents the validattributevalues: skaters acceptassists/goals/points; goalies acceptsavePctg/gaa/shutouts. -
nhl_records_franchise(franchise_id = ...)now translates thefranchise_idargument into acayenneExp=id={id}filter. The records API does not support a path-suffixfranchise/{id}form (returns 404). -
nhl_records_award_details()– replaced the brokenfranchise_idargument withseason_id(theaward-detailsendpoint acceptsseasonIdfiltering but rejectsfranchiseId). -
nhl_stats_content_module()now guards against unnamed CMS responses that previously crashedclean_names().
Deprecations
- PHF functions:
phf_schedule(),phf_standings(),phf_pbp(),phf_player_box(),phf_team_box(),phf_team_roster(),phf_team_stats(),phf_player_stats(),phf_leaders(),phf_league_info(),phf_game_all(),phf_game_raw(),phf_game_details(),phf_game_summary(). - PHF loaders:
load_phf_pbp(),load_phf_team_box(),load_phf_player_box(),load_phf_schedule(),load_phf_rosters(),update_phf_db(). - Utility:
most_recent_phf_season(). -
Deprecated: nine NHL Edge “top-10” leaderboard wrappers whose upstream endpoints the NHL has removed (every request returns HTTP 404):
nhl_edge_goalie_5v5_top_10(),nhl_edge_goalie_edge_save_pctg_top_10(),nhl_edge_goalie_shot_location_top_10(),nhl_edge_skater_shot_location_top_10(),nhl_edge_skater_shot_speed_top_10(),nhl_edge_skater_speed_top_10(),nhl_edge_skater_zone_time_top_10(),nhl_edge_team_shot_location_top_10(), andnhl_edge_team_skating_speed_top_10(). They now emit alifecycle::deprecate_warn()and returnNULL. The Edge “top-10” wrappers that remain live (skater distance, team skating-distance, team zone-time) are unaffected.
Improvements
-
pwhl_season_id()now retrieves season data dynamically from the HockeyTech API instead of using a hardcoded lookup table. Falls back to hardcoded data when the API is unavailable. - Added internal helpers
.pwhl_api(),.pwhl_modulekit_url(),.pwhl_gc_url(), and.pwhl_resolve_season_id()to reduce JSONP parsing boilerplate across PWHL functions. - Added
lifecyclepackage for formal deprecation management. - Updated
testthatdependency to>= 3.0.0. - Complete test coverage for all 95 exported functions (482 tests).
- Added environment-controlled test toggles (
RUN_NHL_TESTS,RUN_PHF_TESTS,RUN_PWHL_TESTS) viatests/testthat/helper-skip.R. - CI workflow environment variables now match
helper-skip.Rnames. - Updated test expectations to match current API responses.
-
nhl_where_to_watch()returnsNULLgracefully when the NHL/v1/where-to-watchendpoint is unavailable. - Updated
_pkgdown.ymlwith reorganized reference sections and deprecated function categories.
Documentation & Infrastructure
- Updated
CONTRIBUTING.mdwith naming conventions, testing environment variables, conventional commits guide, and deprecation process. - Updated PR and issue templates.
- Updated
CLAUDE.mdand.github/copilot-instructions.mdto reflect v1.0.0 changes and new PWHL endpoints. - Added
data-raw/pr_devel.mddevelopment scratchpad. - Added
cran_comments.mdfor CRAN submission. - Updated
_pkgdown.ymlwith reorganized PWHL reference sections. - Added R CMD check CI workflow and pkgdown deployment workflow.
Housekeeping
Documentation migrated to roxygen2 8.1.0; the full test suite now skips on CRAN (everything runs in CI on every push);
cphrole added toAuthors@R; LICENSE year refreshed; R-hub workflow moved to the rollingr-hub/actions@v1tag (node24 runtime).Added read-only Fox Sports “Bifrost” NHL wrappers (
fox_nhl_*) overapi.foxsports.com/bifrost/v1/nhl/*, complementing theespn_nhl_*family:fox_nhl_pbp()(period-based play-by-play),fox_nhl_boxscore(),fox_nhl_odds(),fox_nhl_team_roster(),fox_nhl_team_stats(),fox_nhl_team_gamelog(),fox_nhl_standings(),fox_nhl_league_leaders(). Flatten Fox’s layout JSON into tidyfastRhockey_datatibbles. Parallels the cfbfastR / hoopR / sportsdataverse-pyfox_*families.Added live HockeyTech wrappers for AHL, OHL, WHL, and QMJHL (
<lg>_schedule(),<lg>_pbp(),<lg>_standings(),<lg>_teams(),<lg>_team_roster(),<lg>_player_stats(),<lg>_leaders(),<lg>_game_summary(),<lg>_season_id(),most_recent_<lg>_season()).Added on-ice / Corsi-Fenwick / TOI analytics across all five HockeyTech leagues (
*_game_shifts(),*_player_toi(),*_game_corsi()). Corsi/Fenwick are proxies — the feed has no missed-shot event (corsi_includes_missed).pwhl_pbp()now returns a superset: addedshot_distance,shot_angle,scoring_chance,on_ice_home,on_ice_away, coordinate-transform + clock columns, andblocked_shot/hitevents.
ESPN NHL endpoints
- Added a comprehensive family of ESPN NHL endpoint wrappers (
espn_nhl_*, 125 functions) covering the full ESPN hockey API surface across the site, web, and core hosts — game data (espn_nhl_pbp,espn_nhl_team_box,espn_nhl_player_box,espn_nhl_game_all,espn_nhl_summary,espn_nhl_scoreboard,espn_nhl_schedule,espn_nhl_standings), athletes, leaders, season structure, event detail, and reference catalog. Each returns a wide, self-describingfastRhockey_datatibble with a documented column table, built on a shared league-generic helper layer. Endpoints ESPN does not populate for the NHL degrade gracefully to an empty frame with a warning.
Data loaders
- Added 13 naming-parity aliases for sportsdataverse-py compatibility:
load_nhl_pbp_full()(parity alias ofload_nhl_pbp(), which already serves the fullnhl_pbp_fullrelease),load_nhl_team_boxscore(),load_nhl_team_boxscores(),load_nhl_player_boxscore(),load_nhl_player_boxscores(),load_nhl_skater_boxscores(),load_nhl_goalie_boxscores(),load_nhl_schedules()(NHL), andload_pwhl_team_boxscores(),load_pwhl_player_boxscores(),load_pwhl_skater_boxscores(),load_pwhl_goalie_boxscores(),load_pwhl_schedules()(PWHL). Each alias forwards all arguments to its canonical counterpart.
Dependencies
- Migrated the entire package from
httrtohttr2behind a single internal.retry_request()helper, and added session / environment / per-call proxy support viaoptions(fastRhockey.proxy = ...)(documented in?fastRhockey). Function outputs are unchanged. - Raised the minimum R version to 4.1.0 (the new
httr2request helpers use the native|>pipe).
CI: NHL loader + xG tests, and two fixes
-
Fix:
nhl_schedule(include_data_flags = TRUE)failed with`x` and `y` must share the same srcand returned a schedule with no flag columns.load_nhl_games()returns adata.table, so the flag left-join was being routed through the dtplyr backend, and the data.table[, <character>]subset evaluated to the literal column names rather than selecting columns. The index is now coerced to a tibble before the join, so the 16 data-availability flag columns attach correctly. -
Fix: NHL Edge “top-10” leaderboard endpoints the NHL has removed return HTTP 404. The Edge fetch helper now passes
terminate_ontohttr::RETRYso permanent client errors (400/401/403/404/410/422) are not retried — the functions still returnNULLgracefully, but without the wasteful retry loop and log noise. Transient 5xx/timeouts are still retried. -
Test infrastructure:
test-load_nhl.Randtest-calculate_xg.Rno longerskip_on_ci(), so the NHL loaders and the xG pipeline are exercised on CI (xgboostis installed explicitly in the workflow). Loader tests now request seasons that are actually published per table and assert on the keys each release carries.
Documentation: @return column tables for all working functions
- Every working exported function (165 across the NHL, NHL Edge, NHL Records, PWHL, and loader families) now documents its return value with a
col_name | types | descriptiontable, matching the convention used inhoopR,wehoop, andcfbfastR. Functions that return a named list of data frames get one table per frame. Column names and types were captured from live API responses, so the tables reflect the actual returned schema.
nhl_schedule() gains a game_type parameter
-
nhl_schedule()gains agame_typeparameter accepting"both"(default),"regular", or"playoffs". In season mode the function now returns regular-season and playoff games in a single tibble. Three new columns (series_letter,playoff_round,series_game_number) are appended to the output; they areNAon regular-season rows. -
Behavior change:
nhl_schedule(season = ...)previously returned only what theclub-schedule-seasonendpoint provided, which mixed preseason (PR), regular (R), and playoff (P) rows. With this release:-
game_typedefaults to"both", so playoff games are now included by default. Passgame_type = "regular"to restore regular-only behavior. - Preseason (
PR) rows are no longer returned by season-mode calls regardless ofgame_type. Usenhl_schedule(day = ...)to retrieve preseason game schedules.
-
-
nhl_playoff_schedule()is unchanged in its public API; internally it now delegates its HTTP call to a new shared internal helper.fetch_playoff_series(). -
Fix:
nhl_schedule()previously returned the samehome_team_name,away_team_name,home_score,away_score, andvenuevalue in every row regardless of the actual game. Root cause was anifelse(scalar, vec, NA)guard in.parse_schedule_games()and.parse_club_schedule_games()that collapsed each vector to length 1, whichtibblethen recycled across all rows. Replaced withif/else, and added regression tests asserting per-row distinct values.home_team_abbr,away_team_abbr, and the other directly-assigned columns were not affected. -
Hardening:
nhl_player_info()used the sameifelse(scalar, vec, NA)idiom across all 18 of its nullable fields. The function returns a 1-row tibble per player so the bug was masked today, but the latent shape was identical to thenhl_schedule()bug above. Replaced withif/elsefor consistency and to remove the foot-gun before it surfaces (e.g., if the function is ever refactored to handle multiple players).
pwhl_schedule() defaults to combined regular season + playoffs
-
pwhl_schedule()gains agame_typeparameter accepting"both"(default),"regular","playoffs", or"preseason". A newgame_typecolumn is appended labeling each row. -
Behavior change:
game_typenow defaults to"both", so a call such aspwhl_schedule(season = 2024)returns regular-season and playoff games in a single, chronologically ordered data frame. Passgame_type = "regular"to restore the previous regular-only behavior. Preseason is excluded from"both"; request it withgame_type = "preseason". - When a requested
game_typedoes not yet exist for a season (e.g. playoffs for an in-progress season), it is skipped rather than erroring, so"both"still returns the regular-season games that do exist. - The HockeyTech schedule feed exposes no machine-readable date, so rows are ordered by a date parsed locale-independently from the feed’s
"date_with_day"display string. -
Fix:
pwhl_schedule()’swinnercolumn is now derived fromgame_statusand an integer comparison of the goal counts. Previously the character goal counts were compared with>, so a double-digit score sorted lexically ("10" < "9") and could name the wrong winner; games that have not been played now yieldwinner = NA(the prior code emitted a"-"placeholder). PWHL games cannot end in a regulation tie, so the former"Tie"branch is gone.
pwhl_player_game_log() and pwhl_streaks() default to combined types
-
pwhl_player_game_log()andpwhl_streaks()gain the samegame_typeparameter ("both"default, plus"regular","playoffs","preseason") and agame_typecolumn labeling each row. With"both", a player’s regular-season and playoff data are returned together. A game type the player/season has no data in (e.g. playoffs for a non-qualifying team) is skipped rather than erroring, so the call still returns the data that does exist. -
pwhl_transactions()is intentionally unchanged: transactions are not scoped to a game type (the playoff season feed carries none), so a combined view would add no information.
PWHL parity: 3 new NHL loaders + datasets
Three new season-level NHL loaders that bring NHL coverage in line with PWHL. Each is backed by a new release tag on sportsdataverse/sportsdataverse-data and powered by new extractors in fastRhockey-nhl-raw/R/scrape_nhl_raw.R and fastRhockey-nhl-data/R/nhl_data_creation.R.
| function | release tag | rows per game |
|---|---|---|
load_nhl_officials() |
nhl_officials |
one per official (refs+lins) |
load_nhl_shots_by_period() |
nhl_shots_by_period |
one per team per period |
load_nhl_shootout() |
nhl_shootout |
one per shootout attempt |
nhl_schedule() data-availability flags
nhl_schedule() gained an include_data_flags = FALSE parameter. When TRUE, the live schedule is left-joined against the cached nhl_games_in_data_repo index from the data repo and gains 16 logical columns (PBP, team_box, player_box, skater_box, goalie_box, game_info, game_rosters, scoring, penalties, scratches, linescore, three_stars, shifts, officials, shots_by_period, shootout) telling you which pre-compiled datasets cover each game. The schedule files in fastRhockey-nhl-raw/nhl/schedules/ and the master schedule on the data repo carry these same flags.
Richer per-game JSON in fastRhockey-nhl-raw
scrape_nhl_raw.R now writes four additional top-level keys into both nhl/json/raw/{game_id}.json and nhl/json/final/{game_id}.json:
-
officials— list of{role, name}(referees first, linesmen second) -
shots_by_period— long-form per-team-per-period shot totals -
shootout— per-attempt summary (NULL if game didn’t reach SO) -
plays_by_period— OLD-format index ofplay_indicesper period -
on_ice/on_ice_plus/penalty_box(final-state reconstruction, derived from the processed PBP) — populated only in thefinal/variant since they need fastRhockey-enriched on-ice columns
Refactor: NHL loaders consolidated into R/nhl_loaders.R
All NHL season-level loaders and the shared .nhl_release_loader() helper now live in R/nhl_loaders.R, mirroring the PWHL convention (R/pwhl_loaders.R). The empty R/nhl_pbp.R file was removed since it never contained an actual nhl_pbp() scraper — only loaders. Public signatures and return types are unchanged.
New NHL Edge Analytics (33 functions)
Wraps the NHL Edge advanced-metrics endpoints under https://api-web.nhle.com/v1/edge/.... Every wrapper accepts an optional season argument (4-digit end year, e.g., 2025) — when omitted, the /now form is used to fetch the current season. All wrappers share an internal .nhl_edge_api() helper in R/helpers_nhl_edge.R.
New NHL Records API integration (25 functions)
First-time integration with https://records.nhl.com/site/api/. All wrappers share an internal .nhl_records_api() helper in R/helpers_nhl_records.R that supports cayenneExp filters, limit/start pagination, and the records-API response shape ({data, total}).
- Franchise:
nhl_records_franchise(),nhl_records_franchise_detail(),nhl_records_franchise_totals(),nhl_records_franchise_team_totals(),nhl_records_franchise_season_results(),nhl_records_franchise_playoff_appearances() - Player:
nhl_records_player(),nhl_records_player_byteam(),nhl_records_player_stats(),nhl_records_skater_real_time_stats_season(),nhl_records_skater_real_time_stats_career() - Goalie:
nhl_records_goalie_career_stats(),nhl_records_goalie_season_stats(),nhl_records_goalie_shutout_streak() - Draft:
nhl_records_draft(),nhl_records_draft_lottery_odds(),nhl_records_draft_lottery_picks(),nhl_records_draft_prospect() - Awards / HOF:
nhl_records_trophy(),nhl_records_award_details(),nhl_records_hof_players() - League:
nhl_records_officials(),nhl_records_attendance(),nhl_records_venue(),nhl_records_combine()
New NHL Stats REST wrappers (13 functions)
Promotes endpoints that were previously only reachable via nhl_stats_misc()’s generic dispatcher into discoverable, dedicated wrappers. Documentation for nhl_stats_misc() was also updated to enumerate every valid endpoint value.
-
nhl_stats_franchise(),nhl_stats_players(),nhl_stats_glossary(),nhl_stats_country(),nhl_stats_config(),nhl_stats_ping() -
nhl_stats_skater_leaders(),nhl_stats_goalie_leaders(),nhl_stats_skater_milestones(),nhl_stats_goalie_milestones() -
nhl_stats_team_listing(),nhl_stats_game_listing(),nhl_stats_content_module()
New NHL api-web miscellaneous endpoints (6 functions + 3 in-place updates)
-
nhl_wsc_pbp(game_id)– narrative-format play-by-play fromwsc/play-by-play/{gameId}(distinct fromnhl_game_pbp()which usesgamecenter/{id}/play-by-play). -
nhl_draft_tracker()– live draft tracker (draft-tracker/picks/now), distinct fromnhl_draft()which hits the staticdraft/picks/nowendpoint. -
nhl_ppt_replay(game_id, event_number)– event-level replay metadata. -
nhl_ppt_replay_goal(game_id, event_number)– goal-specific replay metadata. -
nhl_postal_lookup(postal_code)– broadcast region lookup by postal code. -
nhl_smartlinks(handle = NULL)– NHL.com smart-link router. -
nhl_scoreboard(date = NULL)– now accepts an optionaldateargument so callers can fetch historical scoreboards (was hardcoded to/now). -
nhl_meta(game_id = NULL, year = NULL, series_letter = NULL)– added a third branch formeta/playoff-series/{year}/{seriesLetter}. -
nhl_draft_year(year, round = NULL)– whenroundisNULLor"all", the function now hits the/draft/picks/{year}/allshortcut in a single request instead of looping per round.
New helper aggregators inspired by nhl-api-py (6 functions)
Convenience wrappers that orchestrate multiple endpoint calls into one tidy data frame:
-
nhl_game_ids_by_season(season, game_types, team_abbr, sleep_rate)– iterates every team’s season schedule and returns the deduplicated set of game IDs. -
nhl_all_players_by_season(season, sleep_rate)– iterates every team’s roster and flattens forwards/defensemen/goalies. -
nhl_player_career_stats(player_id)– combinesplayer/{id}/landingwith the season-by-seasonseasonTotalspayload into a career frame. -
nhl_team_summary_range(start_season, end_season)– multi-season team summary loop overnhl_stats_teams(report_type = "summary"). -
nhl_skater_summary_range(start_season, end_season)– same for skater summary. -
nhl_goalie_summary_range(start_season, end_season)– same for goalie summary.
Endpoint mapping + OpenAPI specs
-
data-raw/nhl_missing_endpoint_function_mapping.md– table of every documented NHL API endpoint and its proposed/implemented fastRhockey wrapper, sourced from dfleis/nhl-api-docs, RentoSaijo/nhlscraper, and coreyjs/nhl-api-py. -
data-raw/nhl_api_web_openapi.{json,yaml}– OpenAPI 3.0.3 spec forapi-web.nhle.com/v1/(132 endpoints). -
data-raw/nhl_stats_rest_openapi.{json,yaml}– OpenAPI 3.0.3 spec forapi.nhle.com/stats/rest/{lang}/(21 endpoints). -
data-raw/nhl_records_openapi.{json,yaml}– OpenAPI 3.0.3 spec forrecords.nhl.com/site/api/(442 endpoints). -
data-raw/_gen_openapi.py– regenerator script.
New NHL Loaders
Ten new season-level loaders that pull pre-compiled NHL datasets from new release tags on sportsdataverse/sportsdataverse-data. All accept a seasons vector (Min: 2011) and return a fastRhockey_data data frame, mirroring the existing load_nhl_*() API:
| function | release tag | rows per game |
|---|---|---|
load_nhl_skater_box() |
nhl_skater_boxscores |
one per skater |
load_nhl_goalie_box() |
nhl_goalie_boxscores |
one per goalie |
load_nhl_game_rosters() |
nhl_game_rosters |
one per dressed player |
load_nhl_game_info() |
nhl_game_info |
one |
load_nhl_scoring() |
nhl_scoring |
one per goal |
load_nhl_penalties() |
nhl_penalties |
one per penalty |
load_nhl_three_stars() |
nhl_three_stars |
up to three |
load_nhl_scratches() |
nhl_scratches |
one per scratched player |
load_nhl_linescore() |
nhl_linescore |
one |
load_nhl_shifts() |
nhl_shifts |
one per shift |
The six pre-existing loaders (load_nhl_pbp(), load_nhl_pbp_lite(), load_nhl_player_box(), load_nhl_team_box(), load_nhl_schedule(), load_nhl_rosters()) were refactored to share a single internal worker (.nhl_release_loader()) without changing their public signatures or return types.
New PWHL Loaders
Eleven new season-level loaders that pull pre-compiled PWHL datasets from new release tags on sportsdataverse/sportsdataverse-data. All accept a seasons vector (Min: 2024) and return a fastRhockey_data data frame, mirroring the existing load_pwhl_*() API:
| function | release tag | rows per game |
|---|---|---|
load_pwhl_skater_box() |
pwhl_skater_boxscores |
one per skater |
load_pwhl_goalie_box() |
pwhl_goalie_boxscores |
one per goalie |
load_pwhl_team_box() |
pwhl_team_boxscores |
two (home/away) |
load_pwhl_game_info() |
pwhl_game_info |
one |
load_pwhl_scoring_summary() |
pwhl_scoring_summary |
one per goal |
load_pwhl_penalty_summary() |
pwhl_penalty_summary |
one per penalty |
load_pwhl_three_stars() |
pwhl_three_stars |
up to three |
load_pwhl_officials() |
pwhl_officials |
one per official |
load_pwhl_shots_by_period() |
pwhl_shots_by_period |
one per period |
load_pwhl_shootout() |
pwhl_shootout |
one per attempt |
load_pwhl_game_rosters() |
pwhl_game_rosters |
one per dressed player |
The four pre-existing loaders (load_pwhl_pbp(), load_pwhl_player_box(), load_pwhl_schedule(), load_pwhl_rosters()) were refactored to share a single internal worker (.pwhl_release_loader()) without changing their public signatures or return types. # fastRhockey 0.7.0
PWHL functions added
-
pwhl_schedule()function added. -
pwhl_team_roster()function added. -
pwhl_teams()function added.
fastRhockey 0.5.0
- Major improvements to NHL Game PBP Data parsing with shifts in-line via
nhl_game_pbp()function added to matchhockeyR.
fastRhockey 0.4.2
- Fixing issues with
phf_league_info()function for team name inconsistency.
fastRhockey 0.4.1
- Minor logic addition for pbp parsing.
- More under the hood changes to adapt to tidyselect new version guidelines.
-
load_phf_rosters()function added. -
load_nhl_rosters()function added.
fastRhockey 0.4.0
CRAN release: 2022-10-25
- Updates logic to add Montreal Force to teams lists/parsing.
- Under the hood changes to adapt to tidyselect new version guidelines.
fastRhockey 0.3.0
CRAN release: 2022-03-25
- Add print method for all functions with a time stamp and description of the data.
- Add
phf_team_logosdataset to package for reference.
fastRhockey 0.2.1
- hotfix to
helper_phf_pbp_data()penalty code. - add
try()to function examples.
fastRhockey 0.2.0
-
espn_nhl_teams()function added.
fastRhockey 0.0.4
Loader functions for PHF
-
load_phf_pbp()function added. -
load_phf_team_box()function added. -
load_phf_player_box()function added. -
load_phf_schedule()function added. -
update_phf_db()function added.
Player and Team Stats, Leaderboards
-
phf_leaders()function added. -
phf_standings()function added. -
phf_player_stats()function added. -
phf_team_stats()function added. -
phf_team_roster()function added.
fastRhockey 0.0.3
Function naming convention normalization
-
load_phf_game()–>phf_game_all() -
load_phf_pbp()–>phf_pbp() -
load_phf_boxscore()–>phf_team_box() -
load_phf_raw_data()–>phf_game_raw()
