Skip to content
NHL Stats API Integration Into Home Assistant
Python
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/ISSUE_TEMPLATE Update bug_report.md May 4, 2019
custom_components/nhl_api Merge event-support Oct 7, 2019
README.md Clarify installation instructions Nov 2, 2019
automations.md Add automation example based on new event trigger Oct 7, 2019
frontend.md Correct incorrect header sizes Sep 21, 2019
hacs.json
info.md Correct HACS description Oct 14, 2019
no_game.png Update no_game.png Oct 2, 2019
teams.md Correct spelling May 4, 2019
with_game.png

README.md

hacs_badge

Home Assistant NHL API

NHL Stats API Integration Into Home Assistant

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_id 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_id: [TEAM ID FOUND IN STEP 2].
  1. 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_id 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_id: [TEAM ID FOUND IN STEP 2].
  1. Restart Home Assistant one final time.

Configuration

key required type usage
platform true string nhl_api
team_id true integer 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. If not defined, defaults to 5 seconds.

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.

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-Game The scheduled game is with 30 minutes of its scheduled start.
In Progess The scheduled game is live.
In Progress - Critical The scheduled game is within 5 minutes of the 3rd period's end.
Game Over The scheduled game has recently ended.
Final The scheduled game is over and the score is final.

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

attribute type usage
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.

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

attribute type usage
last_goal string Description of the last goal scored in the format "GoalScorer (Season/PlayoffTotal) TypeOfShot, assists: AssistingPlayer1 (Season/PlayoffTotal), AssistingPlayer2 (Season/PlayoffTotal)".
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.
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

You can’t perform that action at this time.