This integration provides real-time scores for teams and athletes in multiple professional (NBA, NFL, NHL, MLB, MLS, and more), college (NCAA), and international (soccer, golf, tennis, racing, cricket) sports using the ESPN Scoreboard APIs, and creates a sensor with detailed data for the competition. Services exist to change and interact with the sensor.

This integration can be used with the ha-teamtracker-card to display the game information in the Home Assistant dashboard.

See the Wiki for FAQs, troubleshooting advise, and custom API configurations that have been already been validated. Please contribute to help others.

This integration is a fork of the excellent ha-nfl custom component by @zacs. Thanks for the starting place!

• Releases for ha-teamtracker and ha-teamtracker-card follow the MAJOR.MINOR.PATCH convention.
• All teamtracker and teamtracker-card releases with the same MAJOR and MINOR version numbers will be compatible, regardless of PATCH version.
• For example, any teamtracker v0.2.x will be compatible with any teamtracker-card v0.2.y.
• Compatibility is not guaranteed across different MAJOR or MINOR version numbers.

TeamTracker will work for any of the hundreds of teams/leagues for which an ESPN scoreboard API exists.

A small subset of the most popular teams/leagues have been pre-configured to simplify their setup. This is referred to as native support. Unfortunately, given the large number of teams/leagues for which APIs exist, it is impossible to provide native support for all of them.

The remaining teams/leagues are still supported, however they require a couple extra steps to set up. This is referred to as configuring a Custom API.

The following leagues are supported natively:

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

It is possible to configure Team Tracker to use any existing ESPN Scoreboard API, not just the pre-configured leagues. This is done by configuring a Custom API.

Sensors with Custom APIs require more steps to set up, however once set up, they behave the same as a natively supported sensor. There is no difference between a team playing in a natively supported soccer league or a non-natively supported soccer league other than the extra steps needed to initially set up the non-natively supported one.

The Custom APIs section below provides more details for setting up Custom API Configurations.

Clone or download this repository and copy the "teamtracker" directory to your "custom_components" directory in your config directory

<config directory>/custom_components/teamtracker/...

Use this button:

OR manually perform the followng steps:

1. Open the HACS section of Home Assistant.
2. In Integrations, click the "+ EXPLORE & DOWNLOAD REPOSITORIES" button in the bottom right corner.
3. In the window that opens search for "Team Tracker Card".
4. Select "Team Tracker Card" from the list
5. Select the "Download" button in the buttom right corner.
6. Select "Download" from the window to download the button.
7. When given the Option, Reload.

The following configuration keys can be used when setting up a Team Tracker sensor.

The league_id configuration key is used the specify the league for the sensor. The following values are valid:

• ATP (Assc. of Tennis Professionals)
• BUND (German Bundesliga)
• CL (Champions League)
• CLA (Conmebol Libertadores)
• 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)
• XFL (XFL)
• WC (World Cup)
• WNBA (Women's NBA)
• WTA (Women's Tennis Assc.)
• XXX (Custom: Specify Sport and League Path)

Using XXX or selecting "Custom: Specify Sport and League Path" from the UI enables the creation of a Custom API and requires the sport_path and league_path configuration keys to be defined.

The team_id configuration key is used the specifiy the competitor to track for the sensor. It can take the form of a Team Abbreviation, Team ID, Athlete Name, Regular Expression, or the Wildcard character (*).

RegEx

For doubles in tennis, rosters are used instead of team names and are in the format of {Player 1} / {Player 2}. You can use a regular expression to match the roster. As an example, if you do not know the order in which the players are listed on the roster, the regular expression .*(?:NADAL|ALCARAZ).*/.*(?:NADAL|ALCARAZ).* will match a doubles match with Nadal and Alcaraz regardless of which player is listed first. The names are not case sensitive.

Wildcard

The Wildcard behavior varies based on the sport.

NOTE: Team Abbreviations and Names may vary based on your local language. While rare, changing the language after a sensor is set up can cause it to stop working.

TeamTracker will use your local language settings when calling the ESPN APIs. Some languages are supported more robustly than others. For example, one language may provide play-by-play updates while another will not. For this reason, you can override your local language. English appears to be the most robustly supported language.

If you set up the sensor using the Home Assistant UI, you can add the override language code via the sensor's Configure button after it has been created.

If you are setting up the sensor using YAML. You can add the api_language configuration key to your YAML configuration.

You should use a standard ISO language code when specifying an override.

The conference_id configuration key is used the specifiy the Conference for the sensor. It should only be used for NCAA football and basketball. Using it for other leagues or sports will cause a NOT_FOUND state.

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.

The following is a list of the college conferences and the corresponding number ESPN uses for their Conference ID. For games involving at least one ranked team, no Conference ID is needed.

The following identifiers are also valid:

Setting the league_id configuration key to XXX or selecting "Custom: Specify Sport and League Path" from the UI, invokes the Custom API Configuration mode. This requires you to set the sport_path and league_path configuration keys. This section explains how to determine the correct values for these keys.

All ESPN APIs use a URL in the following format: https://site.api.espn.com/apis/site/v2/sports/{SPORT_PATH}/{LEAGUE_PATH}/scoreboard where {SPORT_PATH} is the sport and {LEAGUE_PATH} is the league that the team plays in.

For example, for the NFL, the URL is https://site.api.espn.com/apis/site/v2/sports/football/nfl/scoreboard

The Custom API Configuration section of the Wiki contains more details on how to determine the {SPORT_PATH} and {LEAGUE_PATH} as well as some that have been verified to work and some that are known to not be compatible. Please update the Wiki if you try others.

The FAQ in the Wiki also contains an explanation of the types of sports that work with the teamtracker integration and those that currently do not.

Once you have used the resources referenced above to determine the correct values to use for sport_path and league_path, you should use those values in the YAML or UI configuration.

1. On the Integrations page, select the "+ Add Integration" button.
2. Search for the integration labeled "Team Tracker" and select it.
3. Select the desired League from the League List. Select "Custom: Specific sport and league path" to create a Custom API.
4. Enter a value for team's ID in the UI prompt. This can be a the team abbreviation, team ID, athlete name, wildcard, or a regex as explained in the Team ID section.
5. If NCAA football or basketball, enter the Conference ID from Conference ID section if desired.
6. You can also enter a friendly name. If you keep the default, your sensor will be sensor.team_tracker, otherwise it will be sensor.friendly_name_you_entered.
7. If you are setting up a Custom API, a second window will be displayed.
8. Enter the value for the Sport Path for the Custom API.
9. Enter the value for the League Path for the Custom API.

Once the sensor is set up with the UI, you can use the Options Menu to override the API language if desired.

To create a sensor via YAML, add the following configuration to your sensor definitions. Enclose the values in quotes to avoid unrealized conflicts w/ predefined terms in YAML (i.e. NO being interpreted as No):

- platform: teamtracker
  league_id: "NFL"
  team_id: "NO"

After you restart Home Assistant then you should have a new sensor called sensor.team_tracker in your system.

You can overide the sensor default name (sensor.team_tracker) to one of your choosing by setting the name option:

- platform: teamtracker
  league_id: "NFL"
  team_id: "NO"
  name: "Saints"

Using the configuration example above the sensor will then be called "sensor.saints".

To set a Conference ID for an NCAA football or basketball team, use the following:

  - platform: teamtracker
    league_id: "NCAAF"
    team_id: "BGSU"
    conference_id: 15
    name: "Falcons"

To set up a Custom API Configuration, set the league_id to 'XXX' and enter the desired values for sport_path and league_path.

- platform: teamtracker
  league_id: "XXX"
  team_id: "OSU"
  sport_path: "volleyball"
  league_path: "womens-college-volleyball"
  name: "Buckeyes_VB"

To override the API language to Spanish, set the api_lang to 'esp'.

- platform: teamtracker
  league_id: "NFL"
  team_id: "NO"
  name: "Saints"
  api_language: esp

The sensor is pretty simple: the main state is PRE, IN, POST, BYE or NOT_FOUND, but there are attributes for pretty much all aspects of the game, when available. State definitions are as you'd expect:

• PRE: The game is in pre-game state. This happens when ESPN publishes the pre-game info via their API. The lead time varies based on the league.
• IN: The game is in progress.
• POST: The game has completed.
• BYE: Your given team has a bye week this week. Note that attributes available are limited in this case (only abreviation, 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. It can also happen at the end of the season or mid-season when ESPN hasn't published the pre-game info for the next game. See the Wiki for help in troubleshooting tips when you believe the sensor is incorrectly in the NOT_FOUND state.

The attributes available will change based on the sensor's state, a small number are always available (league, team abbreviation, team name, and logo), but otherwise the attributes only populate when in the current state. The table below lists which attributes are available in which states.

Some attributes are only available for certain sports.

TeamTracker supports the following services.

NOTE: The functionality and input parameters of the call_api service are subject to change as new uses emerge. If you have ideas or suggestions for specific use cases, open an Issue so they can be tracked.

Additional details available on the Services tab in Developer Tools.