Be Smart, Go Local.

How To Track Your Favorite Sports Team in Home Assistant

This tutorial guides you in implementing Team Tracker: a custom integration for tracking your favorite sports team or athlete in Home Assistant.

If you’ve ever wanted an easy and simple way to track your favorite NFL or NBA team within Home Assistant, this is the integration for you. Dev vasqued2 has made it super easy to implement a sports tracking dashboard for a variety of different sports, athletes or leagues by developing Team Tracker, a simple integration which polls the ESPN Scoreboard API. There is also a custom card available for displaying the data in Lovelace.

Team Tracker Custom Integration in Home Assistant, Different Sport Layouts

What is Team Tracker?

Team Tracker is a custom integration developed by dev vasqued2 which allows Home Assistant users to easily track their favorite sports teams and athletes. Team Tracker works by pulling live data from ESPN’s Scoreboard API and creates sensor entities within Home Assistant with the information stored as attributes.

The dev also made a custom Team Tracker card to accompany the integration, which fits nicely on any Lovelace view, especially when displayed on a wall mounted tablet.

Which sports can you track?

Team Tracker Integration Different Sports You can Track

You can track a variety of different sports with the Team Tracker integration:

  • Australian Football – AFL (beta)
  • Baseball – MLB
  • Basketball – NBA, WNBA, NCAAM, NCAAW, WNBA
  • Football – NFL, NCAAF
  • Golf – PGA
  • Hockey – NHL
  • MMA – UFC
  • U.S. Soccer – MLS, NWSL
  • International Soccer – BUND (German Bundesliga), CL (Champions League), EPL (English Premiere League), LIGA (Spanish LaLiga), LIG1 (French Ligue 1), SERA (Italian Serie A), WC (World Cup)
  • Racing – F1, IRL
  • Tennis – ATP, WTA
  • Volleyball – NCAAVB, NCAAVBW

What leagues can you track?

Team Tracker Integration Different Leagues You can Track

Within the selected sport, you can track the following leagues by default:

  • ATP (Assc. of Tennis Professionals)
  • BUND (German Bundesliga)
  • CL (Champions League)
  • EPL (English Premiere League)
  • F1 (Formula 1 Racing)
  • IRL (Indy Racing League)
  • LIGA (Spanish LaLiga)
  • LIG1 (French Ligue 1)
  • MLB (Major League Baseball)
  • MLS (Major League Soccer)
  • NBA (National Basketball Assc.)
  • NCAAF (NCAA Football)
  • NCAAM (NCAA Men’s Basketball)
  • NCAAW (NCAA Women’s Basketball)
  • NCAAVB (NCAA Men’s Volleyball)
  • NCAAVBW (NCAA Women’s Volleyball)
  • NFL (National Football League)
  • NWSL (National Women’s Soccer League)
  • PGA (Professional Golfers’ Assc.)
  • SERA (Italian Serie A)
  • UFC (Ultimate Fighting Championship)
  • WC (World Cup)
  • WNBA (Women’s NBA)
  • WTA (Women’s Tennis Assc.)

You can configure Team Tracker to you use a custom API call beyond the preconfigured leagues. This is very useful for International Soccer where ESPN’s API cover 100 different leagues which are not natively supported in the custom integration. We will cover an example further in the tutorial.



  • Open HACS
  • Click + Explore and Download Repositories
  • Under Integrations, search for Team Tracker
  • Select the latest version
  • Click on Download
  • Click to Restart Home Assistant


  • Clone or download the repo
  • Copy the teamtracker directory to config/custom_components/teamtracker/…
  • Restart Home Assistant

The optional custom card is not yet available in HACS. To install it, we need to add a custom resource URL first:

  • In the top right corner of HACS, click the three dots
  • Click Custom Repositories
  • Paste the repo link
  • Select Category Lovelace
  • Click Add
  • Click + Explore and download repositories
  • Search for Team Tracker and download the card
  • Click to Reload your resources
  • If you are using Lovelace in storage mode, don’t forget to add a resource URL


Once you have installed the custom Team Tracker component and card, we can set it up using the UI. When you pick a team and add it through Team Tracker, it will create a sensor which inherits 5 different states:

  • PRE: The game is in pre-game state; ESPN has published the pre-game info via their API
  • IN: The game is in progress.
  • POST: The game has completed.
  • BYE: Your given team has a bye week this week. Attributes available are limited in this case (only abbreviation, name, logo, and last updated time will be available).
  • NOT_FOUND: There is no game found for your team, nor is there a bye. This can happen if an invalid league or team ID has been entered

All other data about the team/league you are tracking will be populated as sensor attributes. Which attributes are available varies greatly with the sport you are tracking. I will create a few different sensors trying to cover different sports, leagues and scenarios.

Finding you team ID

Besides the League ID which we’ve listed above, we also need to specify a Team ID. This is 2, 3 or 4 letter abbreviation ESPN uses in their Scoreboard API. You can usually find those by visiting and looking at the top bar in the UI for the appropriate sport. Another way would be to visit the Team’s page on ESPN and look at the URL. For example, If I wanted the ID for the Boston Celtics I would navigate to:

The abbreviation after /name/, BOS is my team name and I would use that in the Team Tracker integration. Let’s continue with a few examples.

Tracking Individual Teams

Let’s say I want to track the Boston Celtics from the NBA. I would need the League ID NBA and Team ID BOS:

  • In Home Assistant, navigate to Settings
  • Click Devices & Services
  • Under Integrations, press + Add Integration
  • Search for Team Tracker
  • You will be presented with a dialog window in which you fill in the data
  • Click Submit
How to add team in Team Tracker Home Assistant Integration
Team Tracker custom integration sensor attributes for selected team

Team Tracker will add the sensor and populate all available data from the API as sensor attributes. If you’ve also installed the Team Tracker card, you can showcase this in your Lovelace dashboard:

type: custom:teamtracker-card
entity: sensor.boston_celtics

By default, NCAA football and basketball will only find a game if at least one of the teams playing is ranked. In order to find games in which both teams are unranked, you must specify a Conference ID, which is a number used by ESPN to identify college conferences and other groups of teams. Conferences ID’s are not consistent across football and basketball. For a list of Conference IDs, check out this list.

Tracking Individual Athletes

To track individual athletes, we need to specify the athlete’s name in the Team ID field. The more info you provide, the correct the pulled data will be. For example, let’s say I want to track Paddy Pimblett from the UFC and his upcoming fight:

And if we showcase Paddy The Baddy’s upcoming fight in the custom card, we can clearly see he’s going to bounce Jared Gordon’s head of the canvas in 3 days in the T-Mobile Arena in Las Vegas.

Tracking Individual Sports (Wild Card)

You can track individual sports (not teams) with a wild card instead of an athlete’s name by inputting a * in the team_id field. This will provide a different set of data, depending on the sport:

  • Golf: Displays the current leader and competitor in second place
  • MMA: Displays the current active fight or the next upcoming fight if none are active
  • Racing: Displays the current leader and competitor in second place
  • Tennis: Results will be unpredictable due to multiple tournaments and matches in progress at once

For example, let’s say I want to track the next upcoming fight from the UFC I would input UFC in the League field and a * character in the Team/Athlete field. This would generate a dynamic sensor which would populate data with the current active fight (if available) or the next upcoming fight in the UFC:

Tracking With Custom API Calls

If you are interested in tracking a sport or league that is not natively supported in the Team Tracker integration, you can do so by customizing the API call for EPSN’s Scoreboard. For example, ESPN covers over a 100 leagues in International Soccer which are not directly supported by the Integration:

All ESPN APIs use a URL in the following format:{SPORT_PATH}/{LEAGUE_PATH}/scoreboard

To set up a Custom API configuration, you must:

  1. Set league_id to XXX to indicate you are setting up a Custom API Configuration.
  2. Set the sport_path to the desired value.
  3. Set the league_path to the desired value.

To find the sport_path and league_path values, visit the ESPN Explorer API Page

  1. Click on the Score and Schedules API section to expand it.
  2. Select the desired sportName from the first drop down. Use this value in all lower case as your sport_path.
  3. Select the desired leagueName from the second drop down. Use this value in all lower case as your league_path.

In the configuration page, input XXX as the League ID and Team/Athlete ID. This will trigger a second dialog window in which you need to input the sport_path and league_path.

Note: Not all sports and leagues are supported. Visit the integration configuration page for more info.

Customizing the Team Tracker Card

We can tweak the custom card by changing a few of the available variables. Please note, most of these variables will only change when the event is currently ongoing.

type: custom:teamtracker-card
entity: sensor.magali_kempen
outline: true
outline_color: red
show_timeouts: true
show_rank: true
card_title: WTA Tennis
Customize the Team Tracker custom card in Home Assistant

Exclude Sensors From the Recorder

This is a must in my opinion, as the sensor data change very frequently and it will grow your database exponentially if not excluded from your recorder component in Home Assistant. If you would like to read all about optimizing your database, read my full tutorial here: Optimize your Home Assistant Database

To exclude a sensor from the recorder, edit your configuration.yaml file:

  exclude: #Exclude entities
      - sensor.paddy_the_baddy
      - sensor.boston_celtics
      - sensor.ufc


Team Tracker is a pretty neat component for tracking individual leagues, sport teams or athletes within Home Assistant. You can subsequently use the sensor attributes the custom integration provide to create a few automations that will notify you when the game/match/fight/race is about to start. For example:

description: Notify me 1 hour before the next UFC fight
mode: single
  - platform: state
      - sensor.ufc
    attribute: kickoff_in
    to: in 1 hour
condition: []
  - service: notify.mobile_app_s21ultra
      title: UFC
      message: The next UFC fight will start in 1 hour!

We use the kickoff_in attribute to trigger a notification which will notify a mobile device before the event with a custom notification.

12 thoughts on “How To Track Your Favorite Sports Team in Home Assistant”

  1. Any chance of a tutorial on setting up an automation utilizing this integration as a trigger to say…flash your lights when your team scores? I’d copied one I found on Reddit, but as with most things on Reddit, it doesn’t quite work.

    • Hello Ben,

      Yes, you can use the team_score attribute as a number state trigger. For example:
      description: ""
      mode: single
      - platform: numeric_state
      entity_id: sensor.argentina
      attribute: team_score
      above: 0
      condition: []
      - service: light.turn_on
      flash: short
      entity_id: light.dining_room


      • I ended up doing something similar. The ones I’d seen had conditions that don’t really seem necessary, and also seemed to keep the automation from firing. The two I have now only have a time condition (so my lights aren’t going off at 1 am for example) and I added a script that also plays their goal/touchdown song over the speakers.

        I only wish there was a way to make it work with MotoGP, but ESPN doesn’t seem to think that exists…

  2. I want to setup an automation that flashes my lights when the Dallas Cowboys score. I have used the above automation you suggested and it looks like it may work for my Theater Light bulbs (they are HUE and I can set them to FLASH). I do not know how to set FLASH or dim/brighten zwave Dimmer switches throughout the house. Any suggestion would be much appreciated. Thank you

Comments are closed.