The Sources endpoint provides descriptive metadata for programming services like over-the-air terrestrial stations, cable network channels, FAST channels, as well as streaming catalogs. This metadata is typically used to display basic channel information and logo in the EPG UI. Source record metadata population is dependent on the source type, country of origin, and general carriage of the station. While Gracenote strives to collect and populate source records constantly, certain metadata is not applicable or not available for all sources.
The Sources endpoint retrieves 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
Code
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
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.24.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 | Example |
|---|---|---|---|
| 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.
- 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\