Teams Endpoint

The Teams endpoint provides metadata and imagery for the sports teams referenced by the Team Event programs. Team data is separated into a fixed team block (containing country, gender, location/university, members) and more dynamic/changeable teamBrand blocks (containing names, abbreviations, logos), only one of which is active at a time. This facilitates team name changes (for example New Jersey Nets, Brooklyn Nets).

API and Example Responses

API 

http://on-api.gracenote.com/v3/Teams

?updateId=[updateId value]
&limit=[limit value]
&api_key=[your-api-key]

Example Requests

Return full list of teams in batches of 1000:

http://on-api.gracenote.com/v3/Teams?updateId=0&limit=1000&api_key=<your-api-key>3/Teams?updateId=0&limit=1000&api_key=<your-api-key>

Request Parameters

Parameter Required? Description
api_key Yes 24-character key obtained during application registration
updateId No Update token. Defaults to 0. Returns teams beginning with updateId, which is sequential numeric offset received in response.
limit No Batch size. Maximum number of teams to be returned by API. Use with updateId.
teamId No For non-batch lookups. Comma-separated list of teamIDs. Overrides updateId.

Important: Use lookup calls for QA and troubleshooting purposes only. Gracenote does not support lookup APIs for Client production environments.

Response Body

Response Description
teamId numeric id used to specify team or sports franchise
updateId numeric update token, used to determine starting point for next update request
updateDate datetime of last modification
deleted optional indicator, present only when value is 'true', to indicate team can be purged. Deletions are typically due to duplicate entry or other editorial issue
teamBrand within franchise, collection of name and logo information. Team will include multiple teamBrands if team name has changed in past (for example, New Jersey Nets, Brooklyn Nets)
teamBrandId numeric id used to specify teamBrand within team, referenced in program data
active boolean indicating whether teamBrand information is currently active. Only one teamBrand per team is active at any given time. None may be active if team has been retired
officialName official/long team name. For example, Arizona Diamondbacks
properName leading portion of team name. For example, Arizona
nickName ending portion of team name. For example, Diamondbacks
abbreviation team abbreviation or shortened name. For example, ARI
assets team logos, if available, are output for active or sole teamBrand, historical logos not provided. College teams will not include logos here, see University API for university logo
sport.genreId sports genreId, indicating primary sport in which team participates
genres collection of genres associated with team, based on organization memberships. May include non-sport-specific genres, such as Olympics, where applicable
genre ID and name of associated sports genre
university applicable only for college teams. Id and name of university
venue provided if team has a designated primary venue. Id and name of venue
gender value may be Male, Female, Mixed
member parent element to hold team member name and type
type team member type. Currently only 'Head Coach' is output
name team member name, with nameId
type element

(Currently optional) used to identify a team type. Each team is expected to have a type associated with it, and in a future release, the type element will be required. Types are:

  • National: a national team competing in international national team leagues like the FIFA World Cup.
  • Club: a club team competing in domestic and international club team leagues like the NFL and UEFA Champions League.
  • Defined: a double team consisting of two persons like a tennis or badminton double.All_Star: an all-star team competing during all-star matches as for example played in NBA, MLB, NHL and NFL.
  • Placeholder: a placeholder team used when the schedule of a league is already known, but the teams aren’t yet.
  • Constructor: a constructor team as used in Formula 1 specifically.
fromDate and toDate elements

(Optional) For teamBrands, fromDate and toDate used to determine the time period during which a teamBrand was/is active. Even though the fromDate and toDate elements are optional, each teamBrand is expected to have a fromDate and toDate associated with it. In future, these elements will be required. Gracenote will send out advance communication on when this change will be released.
names element

(Optional)For teamBrands to allow support for multiple alias types. The names element will publish a name with attributes of language and type. Each teamBrand is expected to have at least one name of lang=’en’ and type=’default’ associated with it.
colors element

(Optional) Used to identify the primary and secondary color associated with a team.
class element

(Optional) Used to identify a team class. We have the following five classes:

  • Seniors: This class typically refers to adult athletes who compete at the highest level of their sport. It's usually the main professional or elite category.
  • Under 23: This category is designed for young adult athletes, usually between the ages of 18 and 22. It serves as a transitional phase between junior and senior levels.
  • Juniors: Junior classes usually encompass teenage athletes, typically ranging from 14 to 19 years old, depending on the sport.
  • Youth: Youth classes are generally for children and young teenagers, often ranging from around 8 to 14 years old.
  • Amateurs: This class includes athletes of various ages who participate in sports for enjoyment rather than as a profession.
address element

(Optional) to provide more information about the address of the team with city, state and country details.
UniversityGId

(Optional) to identify the University associated with the team.
category “Flag”

For national teams. A team used to either have one logo associated with it, which could either be a flag or an actual logo. For national teams, we will now explicitly add the flag with the category “Flag”. This automatically means the category “Logo” will only be used for actual (club and national) team logos.
category “Flag - circle”

For national teams. Circle flags are widely used to represent countries nowadays, so next to the square flag, we will also introduce a circle flag image with a width and height of 3000 (1:1), which will also be available for each national team.

Example Responses

Below is an example response. Also see Teams XML examples.

Enriched Non-Team Events

Venue and time zone values is populated for non-team sports events to bring data parity with team-events. Non-Team Events (NTEs) are competitions in which the outcome is not predetermined and are not team versus team sports. Some examples of sports with event types NTE are Golf, Tennis, NASCAR, Bowling, etc.

Data Structure and Relationships

Schema

Review the following XML schema definition (xsd) to learn about the data structure, fields, and types for this endpoint.

To explore the relationships among all endpoints, see the interactive schema documentation.

XML Schema URL: http://files.api.gracenote.com/xsd/on_update_teams_3.23.xsd