Sources Endpoint

The Sources endpoint is designed to retrieve Gracenote information for programming services, identified by Gracenote programming service ID (prgSvcId). The Sources schema provides station information, including:

  • prgSvcId, for linking to Schedules API
  • Station name and location
  • callSign
  • Broadcast languages
  • HD/SD attributes
  • Affiliations to broadcast and cable networks
  • Nielsen DMA designations (USA)
  • Station logos

All sources are marked with a unique updateId, denoting current information for the programming service. Changes to any source data will result in assignment of a new updateId, which allows you to pull deltas since last retrieval of source information. Scope of stations can be requested by particular country, lineup, custom station list, or a combination of criteria dependent on customer need. For example, you can request all active stations in USA and Mexico for your feed, and receive deltas for only those stations.

API and Example Responses

API 

http://on-api.gracenote.com/v3/Sources
?updateId=[updateId value]
&limit=[limit value]
&api_key=[client assigned API key]

Request Parameters

Parameter Required? Description
api_key Yes Your API key
updateId No Programming services modified at or after updateId.
limit No Batch size. Maximum number of programming services to be returned.
prgSvcId No For non-batch lookups. Comma-separated list of programming service IDs.

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

Example Responses

See Sources XML examples.

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.

XSD: http://files.api.gracenote.com/xsd/on_update_sources_3.22.xsd

Sources Key Fields

The following data dictionary shows the XPATH of key elements and attributes for source objects. Unless stated otherwise, the XPATH in the tables below is relative to: on/sources/prgSvcs/prgSvc

XPATH Element\Attribute Description Example
@prgSvcId Gracenote unique identifier for a programming service 20459
name/ Name of the programming service WNBC-DT
callSign/ Call sign of the programming service WNBCDT
timeZone/ Time zone that the station is edited in Eastern Observing
ianaTimeZone/ The IANA time zone that the station is edited in America/New York
videoQuality/signalType/ Transmission signal type used by the service. Digital
edLangs/edLang/ RFC 5646 language code for an edit (guide metadata) language of this programming service. en
bcastLangs/bcastLang/ RFC 5646 language code for a broadcast (spoken audio) language of this programming service. en
countriesOfCoverage/country/ The ISO-3166 alpha-3 code for the country of coverage USA
num/ Legacy RF channel number of the broadcast service 35
num/@majorNum Major VCN (virtual channel number) of the broadcast service 5
num/@minorNum Minor VCN (virtual channel number) of the broadcast service 1
marketIds/marketId/ Number code of the market ranking area in which the source is located. 510
reach/ Used to broadly identify the extent of coverage on a given station: Local, Regional, National, International. See Supplemental Controlled Vocabulary (auto-download) for full list/description. Local

Source callsigns follow basic Gracenote standards for broadcast, cable, and satellite channels e.g. WNBC-DT or ESPN HD. Source channel names use the “official” name, or name and callsign requested by the source, e.g. PTV007 / Pluto TV 007 or SN1DFW / Spectrum News 1 - Dallas - Ft Worth. Source names can change.

Source Type

The source type broadly describes the content of the programming service.

XPATH Element\Attribute Description Example
type/ Gracenote categorization of the service type. Full Power Broadcast

Below are some common source types, see Supplemental Controlled Vocabulary (auto-download) for the full list:

Channel Type Definition Example
Broadband Used for providers of on-demand Internet streaming media such as Hulu, Netflix, Amazon Studios, Crackle, Yahoo! Screen, etc. HULU,  NETOV, CRACKOV, AMZONOV
Cable Only  A custom or local channel created for a specific cable system and airs within a particular region. CVCLF, BATCR11, 
Digital Broadcast Network A service which operates as a digital broadcast TV network platform in which programming is primarily available to broadcast/over-the-air/terrestrial TV station affiliates 24 hours a day for digital sub-channel carriage, and this same information can also be made available directly to other multichannel video programming distribution services. ANTENNA, DYSTR, METVN
Full Power Broadcast U.S. definition: A full-power, over-the-air channel operating and following licensing regulations for the FCC. WABC-DT, WNBC-DT
Low Power Broadcast U.S. definition: A channel licensed by the FCC as a low-power, secondary television service. WNYN-LD, WNYF-CD
Network U.S. definition: a "Network" is a program distributor which distributes more than 15 hours of prime time programming a week to at least 25 affiliates in at least 10 states for the U.S. ABC, NBC, CBS
Radio Station A channel transmitting over-the-air radio audio.  KBSGFM, MSLXM
Satellite A channel whose programming is available direct from satellite or cable to consumers. Programming is not available over-the-air. HBO, DSC, FOOD
Streaming Gracenote definition:  A channel whose programming is broadcast on the Internet in a linear fashion. AESTR, SHOWSTR, IFCSTR

Attributes

Source attributes broadly describe the transmission method, default definition standard, and indication of non-standard programming/content.

XPATH Element\Attribute Description Example
attribs/attrib/ Attribute(s) describing the programming service. Digital, HDTV

Below are some common source attributes, see Supplemental Controlled Vocabulary (auto-download) for the full list:

Attribute Definition
Adult Indicates that the channel is carrying “Adult only” genre programming.
Analog Indicates that the channel’s signal is an analog transmission. This only allows for the attribute of “SDTV”
Audio Indicates that the channel is carrying predominantly music audio type programming, fed by satellite.
Digital Indicates that the channel’s signal is a digital transmission. This allows for attributes of “SDTV, ” “HDTV,” and “UHDTV”
HDTV Indicates that the channel’s signal is a “High Definition” transmission. “HDTV” generally encompasses a more specific set of HDTV high-definition video modes such as 720i, 720p, 1080i, 1080p, etc.
Pay-per-view Indicates that the channel is pay-per-view.
Premium Indicates that the channel is usually high-profile, commercial-free and viewers have to pay a premium to receive it.
SDTV Indicates that the channel’s signal is a “Standard Definition” transmission.
Sports Indicates that the channel's programming content is mainly sports events or sports-related programs.
UHDTV Indicates that the channel’s signal is an “Ultra High Definition” transmission. “HDTV” generally encompasses a more specific set of HDTV high-definition video modes such as 2160p, and consumer terms “4K” and “8K”

Relationships

Relationship types indicate the given channel’s relationship to other channels.

XPATH Element\Attribute Description Example
relationships/relationship/ A second programming service to which this one is related. 11705
relationships/relationship/@type A description of the nature of the relationship between two programming services. Digital Version of

Below are some common relationship types, see Supplemental Controlled Vocabulary (auto-download) for the full list:

Type Definition
Digital Sibling of Indicates the multicast channels airing additional programming on a digital channel's tower/equipment.
Digital Version of Indicates that a channel is digitally compressing the signal of an analog station to simulcast or multicast additional programming from the analog station's tower/equipment. This attribute is primarily designated for DT stations as a Digital Version of its Analog counterpart (i.e WTENDT is the Digital Version of WTEN).
HD Version of Indicates a channel that airs same programming as SD channel, but in HD.
SD Version of Indicates a channel that airs same programming as HD channel, but in SD.
UHD Version of Indicates a channel that airs same programming as another channel, but in Ultra HD (4K). 
Streaming Version of A channel that is a feed offered by a traditional linear source, made available over the internet. Programming on a streaming channel does NOT need to be identical to linear feed.
Time Zone Sibling of Indicates a channel that is an exact duplication of another (parent) channel, but broadcasts in a different time zone.
Can Use Branded Images From Indicates programming services that have permission to utilize branded images from another programming service. Ex. PBS affiliate can use branded images from PBS

Transport Identifiers

Transport identifiers are transmitted in the broadcast signal of the channel and can be used to map broadcast channels to channels in EPG data. Depending on the country, different broadcast standards are in use - for example ATSC in North America, DVB in EU and ANZ, ISDB in most of LatAm and Japan. Gracenote currently supports ATSC TSID in the US at the source level.

XPATH Element\Attribute Description Example
transportIds/transportId/ Source transport identifier 2159
transportIds/transportId/@system Source transport identifier system ATSC
transportIds/transportId/@type Source transport identifier type TSID

Imagery

Source logos are collected for the most carried stations in each country and major provider. Logos are not available for every source. Gracenote typically does not collect logos for individual broadcast affiliates, but instead references the parent network logo.

XPATH Element/Attribute Description Example
assets/asset/@assetId Gracenote image identifier s28719_lw_h15_ac
assets/asset/@type MIME content type image/png
assets/asset/@lastModified Timestamp of last asset/metadata modification 2019-09-21T19:20:11Z
assets/asset/@width Maximum image width 3840
assets/asset/@height Maximum image height 2160
assets/asset/@primary Whether image is primary in the category true
assets/asset/@category Image category Source Logo - dark
assets/asset/@ratio Image aspect ratio 16:9
assets/asset/URI/ Relative Image URI assets/s28719_lw_h15_ac.png

The image asset structure and general handling logic is common to images of all entities, however, categories and aspect ratios vary depending on the entity. The following table provides the source logo categories and aspect ratios.

Category Description Ratios
Source Logo - dark Logo that works on a guide/page with a dark background. 4:3, 16:9
Source Logo - gray De-saturated version of the logo - also called monochromatic 4:3, 16:9
Source Logo - light Logo that works on a guide/page with a light background. 4:3, 16:9
Source Logo - white All-white version of the channel logo - also called knockout version. 4:3, 16:9
Parent Source Logo - dark Logo of the parent network associated with the affiliate station. 4:3, 16:9
Parent Source Logo - gray Logo of the parent network associated with the affiliate station. 4:3, 16:9
Parent Source Logo - light Logo of the parent network associated with the affiliate station. 4:3, 16:9
Parent Source Logo - white Logo of the parent network associated with the affiliate station. 4:3, 16:9

For more information, see the supplementary document On API Image Category & Tier Definitions (auto-download).

Entity Relationship Diagram

The following ERD illustrates the ID relationships from a Source record.

A screenshot of a computer Description automatically generated

  • The “prgSvcId” uniquely identifies each source record
    • on\sources\prgSvcs\prgSvc\@prgSvcId
  • Sources within channel lineups relate to this element:
    • on\lineups\lineup\channelList\channel\@prgSvcId
  • Sources within schedules relate to this element:
    • on\schedules\schedule\@prgSvcId
  • Sources within programs relate to these elements:
    • on\programs\program\originalNetwork\@prgSvcId
    • on\programs\program\seasons\season\originalNetwork\@prgSvcId
    • on\programs\program\releases\release\prgSvcId\