search

JayBlackedOut / hass-nhlapi

NHL Stats API Integration Into Home Assistant
69 stars 18 forks source link

readme

hacs_badge

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.

  6. In the HACS Store, search for NHL and find the NHL API integration and install it.
  7. From the teams.md file in this repository, find the team_abbrev of the team you would like to track.
  8. Restart Home Assistant to allow the required packages to be installed.
  9. 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]
  10. 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

Drew Hynes' Unofficial Documentation

Adam Pritchard's NHL Score API

The Reddit Post that Inspired this Project