NHLe API Library

A modern TypeScript wrapper around the public NHL GameCenter and EdgeStats APIs with simple, composable functions and strong TypeScript typing.

Overview

The library exposes a small, functional surface over the NHL "Game Center" and related APIs and ships with rich response types for all Game Center endpoints.

• Written in TypeScript and published as ESM/CJS
• Thin functional wrappers over official NHL API routes
• Fully-typed Game Center responses (game, team, player, draft, misc)
• Code-defined configuration for timeouts, language and logging

Installation

npm install nhle-api

The package ships both ESM and CJS builds; use standard import/require according to your toolchain.

Quick Start

The primary entrypoint is the Game Center API namespace gc:

import{gc}from'nhle-api';// Get game landing page dataconstgameInfo=awaitgc.game.landing(2023020001);// Get live play-by-playconstplayByPlay=awaitgc.game.playByPlay(2023020001);// Get boxscoreconstboxscore=awaitgc.game.boxscore(2023020001);// Get today's scoresconstscores=awaitgc.score(newDate());// Get current scoreboardconstscoreboard=awaitgc.scoreboard();// Get team rosterconstroster=awaitgc.team.roster('TOR');// Get player landing page (Connor McDavid)constplayer=awaitgc.player.landing(8478402);

Configuration

Basic behavior is configured in src/config/index.ts:

exportconstconfig={timeout: 10000,language: 'en',logLevel: 'debug',};

You can inspect the active configuration at runtime:

import{config,logConfig}from'nhle-api';console.log(config.timeout,config.language,config.logLevel);logConfig();

See docs/CONFIGURATION.md for more details.

Top-Level Exports

The package root nhle-api re-exports the main API namespaces, configuration utilities, constants, and public types:

// Game Center API (fully typed)import{gc}from'nhle-api';// Edge Advanced stats (in progress, API surface may change)import{adv}from'nhle-api';// Code-defined configuration helpersimport{config,logConfig}from'nhle-api';// Shared type exports (Game Center response types, parameter types, etc.)importtype{GameLandingResponse}from'nhle-api';

Notes on Edge APIs

• adv (Edge Advanced) is available but still considered in development, but ready for preliminary use.
• The stats (Edge Stats) namespace is not exported at the moment and will be introduced in a future release once implementation is ready.

Toolkit Entry Point

Use the nhle-api/toolkit subpath when you only need NHL constants and shared helpers. It does not expose API endpoint namespaces or environment configuration:

import{NHL,getCurrentSeason,resolvePath,}from'nhle-api/toolkit';constseason=getCurrentSeason();constteamPath=resolvePath('/teams/{team}',{team: 'TOR'});

This entry point exports NHL, date helpers, resolvePath, team branding data, historical team palettes, and official logo URL helpers.

Game Center API (gc)

gc is the primary namespace for accessing live and historical NHL data.

gc.game – Game Data

• playByPlay(gameId) – Full live play-by-play event stream
• boxscore(gameId) – Boxscore and team/player stats for a game
• landing(gameId) – Game landing page data (summary, lines, etc.)
• reports(gameId) – Game reports / right-rail data
• schedule(date?) – Schedule for a given date (defaults to today)
• scheduleCalendar(date?) – Calendar-style schedule for a date
• playoffBracket(year?) – Playoff bracket for a given year
• playoffSeries(season?) – Playoff series information for a season
• playoffSeriesSchedule(season, seriesLetter) – Schedule for a playoff series
• whereToWatch() – Regional broadcast / streaming info
• networkTVSchedule(date?) – National TV schedule
• wsc.gameStory(gameId) – Game story from the web service collection
• wsc.playByPlay(gameId) – Play-by-play from the web service collection
• pptReplay.goal(gameId, eventId) – Goal replay data for a specific event
• pptReplay.event(date?) – Replay events for a given date (does not appear to be functional at this time)

gc.score – Scores & Scoreboards

• score(date?) – Scores for a given date (defaults to today)
• scoreboard() – Current live scoreboard

gc.team – Team Data

• roster(teamCode, season?) – Team roster for a given season
• rosterSeasons(teamCode) – Available roster seasons for a team
• prospects(teamCode) – Team prospects
• clubStats(teamCode, season?) – Club stats for a team/season
• clubStatsSeason(teamCode) – Season-level club stats
• standings(date?) – Standings for a given date
• standingsSeason() – Season standings
• schedule.now(teamCode) – Current schedule segment for a team
• schedule.month(teamCode, month) – Team schedule for a given month
• schedule.season(teamCode, season) – Full season schedule for a team

gc.player – Player Data

• landing(playerId) – Player landing page data
• gameLog(playerId, season?, gameType?) – Game log for a player
• spotlight() – Featured players (spotlight carousel)
• search(query) – Player search
• statsLeaders.season(season?, gameType?, category?, limit?) – Season stat leaders
• statsLeaders.current(gameType?, category?, limit?) – Current stat leaders

gc.draft – Draft Data

• picks(year?) – Draft picks for a given year
• tracker() – Draft tracker
• rankings(year?) – Draft rankings (all, NA/International, skaters/goalies)

gc.misc – Miscellaneous

• seasons() – All NHL seasons
• meta.game(gameId) – Game metadata
• meta.gameVideo(gameId) – Game video metadata
• postalLookup(postalCode) – Postal/ZIP lookup (location info)
• location() – Location info for current context
• partnerGame(country, date?) – Partner game information

Types

The library exports strongly-typed response shapes and parameter types for all Game Center endpoints from the types bundle:

• Response types for gc.game.*, gc.team.*, gc.player.*, gc.draft.*, gc.misc.*
• Common enums and helper types (position codes, team codes, schedule state, etc.)

Error Handling and NHLError

Under the hood, low-level HTTP requests use a shared NHLClient and ErrorHandler which normalize HTTP/network failures into a single NHLError shape.

• All non-2xx responses and network/timeout failures are converted to an NHLError instance.
• Errors are categorized (client/server/network) with optional context (endpoint, method, status code).
• High-level helpers expose these via the APIResponse<T> union so you can safely branch on status without catching exceptions.

Typical usage pattern:

import{gc}from'nhle-api';importtype{APIResponse,GamecenterLanding}from'nhle-api';constresult: APIResponse<GamecenterLanding>=awaitgc.game.landing(2023020001);if(result.success){console.log(result.data);}else{// NHLError instance with rich metadataconsole.error(result.error.message);}

Roadmap / Status

• ✅ Game Center endpoints fully wired with response types
• ✅ Code-defined configuration utilities (config, logConfig)
• ✅ Error handling via NHLError and structured error responses internally
• 🚧 Edge Advanced (adv) API surface and types are in development
• ⏳ Edge Stats (stats) API will be added in a future minor release

For a detailed list of changes and recent work on response types and endpoint coverage, see CHANGELOG.md.

Docs

• Configuration - Code-defined configuration and default values
• Query Builder Guide - Cayenne query builder for stats APIs

Contributing

This project is still evolving and feedback is very welcome.

• Bug reports / issues: If an endpoint returns unexpected data, response parsing fails, or types don’t match the real API, please open a GitHub issue with the endpoint, parameters, and (sanitized) sample payloads if possible.
• Type improvements: PRs or issues that improve response coverage, fix missing/incorrect fields, or refine enums and unions are particularly helpful.
• JSDoc / docs: Additions or corrections to JSDoc on public types and functions, or clarifications to the guides in docs/, are also very much appreciated.

Before filing an issue, check the CHANGELOG.md for recent changes and breaking notes, and include the library version you’re using.

Support

If you find this library helpful, consider supporting its development:

License

This project is licensed under the MIT License. See the LICENSE file for details.