Breaking Change!

On September 21, 2023, the NHL started retiring their API endpoints and introduced a new API. Like the previous API, the new one is public but undocumented/not publicized. This custom component has been reworked to consume the new API.

Unfortunately, the last_goal attribute has been removed from the exposed information since the new API does not readily provide human readable goal descriptions.

Help the effort to continue documenting the new endpoints by joining the fine folks in the NHL LED Scoreboard discord!

Home Assistant NHL API

NHL Stats API Integration Into Home Assistant: Bring live score updates into Home Assistant and fire automations when your team scores!

The sensor will only fetch data every 10 minutes when the game is not live and will then update at the user defined frequency (or every second if undefined) once the game is live. Credit goes to @mastermc0.

Note: The NHL updates their endpoints every 15 seconds.

Installation: Manual

1. Copy the nhl_api folder to the custom_components folder in your Home Assistant configuration directory.
2. From the teams.md file in this repository, find the team_abbrev of the team you would like to track.
3. Restart Home Assistant to allow the required packages to be installed.
4. Add the following minimum code in your configuration.yaml file. See Configuration for more advanced options:

sensor:
  - platform: nhl_api
    team_abbrev: [TEAM ABBREV FOUND IN STEP 2]

5. Restart Home Assistant one final time.

Installation: HACS

This method assumes you have HACS already installed.

1. In the HACS Store, search for NHL and find the NHL API integration and install it.
2. From the teams.md file in this repository, find the team_abbrev of the team you would like to track.
3. Restart Home Assistant to allow the required packages to be installed.
4. Add the following code in your configuration.yaml file. See Configuration for more advanced options:

sensor:
  - platform: nhl_api
    team_abbrev: [TEAM ABBREV FOUND IN STEP 2]

5. Restart Home Assistant one final time.

Configuration

key	required	type	usage
platform	true	string	nhl_api
team_abbrev	true	string	Identifies the team to be tracked by the sensor. See teams.md.
name	false	string	Friendly name of the sensor. If not defined, defaults to: 'NHL Sensor'.
scan_interval	false	integer	Number of seconds until the sensor updates its state when the game is live. If not defined, defaults to 1 second.

Warning! Setting your scan_interval to a low number leads to more writes to your disk. It is recommended to not set the scan interval to less than 5 if running Home Assistant on a Raspberry Pi. Also, each time the sensor updates (i.e. at each scan interval), anywhere from ~300B to ~25KB of data is consumed. Keep this in mind if you have a low internet data cap.

Example

sensor:
  - platform: nhl_api
    team_abbrev: mtl
    name: Canadiens
    scan_interval: 30

Exposed Information

The sensor will expose the status of the tracked team's scheduled game for the day. The state can be:

state	description
Next Game Date & Time	The next game is not yet close to starting. Will return date and time of the next game.
PRE	The scheduled game is with 30 minutes of its scheduled start.
LIVE	The scheduled game is live.
CRIT	The scheduled game is within 5 minutes of the 3rd period's end.
OVER	The scheduled game has recently ended.
FINAL	The scheduled game is over and the score is final.
OFF	The scheduled game is over and the score is official
No Game Scheduled	There are no scheduled games upcoming.

The sensor will return the following state attributes whether or not a game is in progress:

attribute	type	usage
national_broadcasts	list	The national broadcast stations for the current/upcoming game.
away_broadcasts	list	The away team's broadcast stations for the current/upcoming game.
home_broadcasts	list	The home team's broadcast stations for the current/upcoming game.
away_id	integer	Identifies the away team by team id as found in teams.md.
home_id	integer	Identifies the home team by team id as found in teams.md.
away_name	string	The name of the away team.
home_name	string	The name of the home team.
away_logo	string	The url to the away team's logo.
home_logo	string	The url to the home team's logo.
next_game_date	string	The date of the next game.
next_game_time	string	The time of the next game. This will be localized based on your Home Assistant configured timezone.
next_game_datetime	string	The date and time of the next game. This will be localized based on your Home Assistant configured timezone.

The sensor will also return the following state attributes when a game is in progress:

attribute	type	usage
goal_type	string	At what strength the goal was scored such as EVEN, PPG, SHG, etc.
goal_team_id	integer	The id of the team that scored the last goal.
goal_event_id	integer	The event id of the goal generated by the API.
goal_team_name	string	The name of the team that scored the last goal.
away_score	integer	The number of goals scored by the away team.
home_score	integer	The number of goals scored by the home team.
away_sog	integer	The number of shots on goal by the away team.
home_sog	integer	The number of shots on goal by the home team.
current_period	string	The current period.
time_remaining	string	The time remaining in the current period.
goal_tracked_team	boolean	Returns true if the last goal was scored by the team being tracked. Otherwise, returns false. Can be useful for goal alerts.

Examples

Display info in the front end: frontend.md
Sample automations: automations.md

Objectives Checklist

• Consume undocumented NHL Stats API locally with the least amount of resources possible.
• Pass information to Home Assistant as sensor data. (ex. Next game scheduled, live scores, goal description, etc.)
• Create a "goal" event platform to use as a trigger for automations.
• Display the information in the front-end in its own Lovelace card.
• Add support for HACS.

Resources

The Undocumented NHL Stats API

Drew Hynes' Unofficial Documentation

Adam Pritchard's NHL Score API

The Reddit Post that Inspired this Project