Lineups Endpoint
The Lineups endpoint provides localized channel lineup metadata for live linear cable, satellite, terrestrial, and streaming services. Channel Lineups represent a list of stations for a video provider or service that is available in a specific country, geographic location, or postal code.
Over-the-air lineups provide a list of channels that can be received within a single postal code. Cable/Telco and Satellite lineups include a set of “headends” (physical facilities) that provide service for one or more postal codes. Each “headend” can contain one or more specific channel lineups identified by a device type.
Channel Lineups are a general representation of the localized list of channels for a specific service provider. They are not an exact list of channels that a user can receive or subscribe to, nor do they represent provider specific subscriptions or packages.
API and Example Responses
The channel lineup record has two basic presentations:
- Over-the-Air (OTA, DIGITAL)
- Cable (CABLE, MVPD, SATELLITE, DIGITAL_BROADCAST, IPTV, OTT, VIRTUAL)
- One or many postal codes are assigned for the service area.
- List of station prgSvcIds, dial position number, effective and expiration dates.
API
http://on-api.gracenote.com/v3/Lineups ?updateId=[updateId value] &limit=[10 max, values >10 are ignored] &api_key=[your-API-key]
Important: Use lookup calls for QA and troubleshooting purposes only. Gracenote does not support lookup APIs for Client production environments.
Response Body
| Response | Description |
|---|---|
| country ID | the ID of the lineup country's isoCode as well as the isoCode value in line with the controlled vocabulary endpoint |
| type | type of service (e.g., Cable, Satellite, OTA) |
| lineup Id | alphanumeric id of the lineup (e.g., USA-CA00053-L) |
| headend Id | alphanumeric id of the headend (e.g., USA-CA00053) |
| headend | name of the provider (e.g., Charter Spectrum) |
| device type | service provider designation for device type (e.g., “L” – Rebuild digital) |
| location | location of headend, usually city name; for national lineups, location will be set to country name |
| mso | name of the multi-system operator, will not be present for small or independent providers or for certain lineup types (e.g., Virtual) |
| mso Id | numeric id of the multi-service operator (e.g., 13890) |
| market type | type of market – currently only supporting DMA |
| market Id | numeric id of the DMA market (e.g., 803) |
| market | name of the DMA market (e.g., Los Angeles) |
| postal codes | list of postal codes in which the service is available |
| channel list | list of channels that are part of the service, referenced by prgSvcId, including the channel number of the channel within the service |
Request Parameters
| Parameter | Description |
|---|---|
| country | Country in which the lineups are located. Use the three character country value as based on the IETF BCP 47 standard. |
| postalCode | Individual, country specific postal code where this lineup is available. |
| api_key | Your API key |
Example Requests
Retrieve all lineups available for a single specific country and postal code.
http://on-api.gracenote.com/v3/Lineups?country=USA&postalCode=12804&api_key=123456
Best Practices
- Use a proper 3-character country code from the IETF BCP 47 standard.
- Use a properly formatted country postal code.
- Be aware that your specific API key and entitlement will have constraints on the available countries/postal codes/lineups.
Retrieve all lineups available for a single specific headend ID.
http://on-api.gracenote.com/v3/Lineups?headend=USA-SC39419&api_key=123456
Request Parameters
| Parameter | Description |
|---|---|
| headend | Gracenote unique ID of the headend. |
| api_key | Your API key |
Best Practices
- Use a headend value retired from your complete update method.
- Be aware that your specific API key and entitlement will have constraints on the available headends/lineups.
Retrieve a single lineup for a specific lineup ID.
http://on-api.gracenote.com/v3/Lineups?id=USA-NY31579-X&api_key=123456
Request Parameters
| Parameter | Description |
|---|---|
| id | Gracenote unique ID of a channel lineup. |
| api_key | Your API key |
Best Practices
- Use a lineup ID value retired from your complete update method.
- Be aware that your specific API key and entitlement will have constraints on the available lineups.
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.
XML schema URL: http://files.api.gracenote.com/xsd/on_update_lineups_3.22.xsd
Entity Relationship Diagram
The following ERD illustrates the ID relationships from a lineup record to other relevant endpoint objects within On API.
- The lineupId uniquely identifies each channel lineup.
- It has no real relational value within the API and other objects.
- The /channelList/channel/@prgSvcId identifies the specific station in a lineup
- The lineup prgSvcId can point to a source record prgSvcId for additional metadata such as callSign, channel name, and channel logo.
- The channel list prgSvcId is also essential in collecting station schedules to create the program guide for the provider.
Lineups Key Fields
Unless stated otherwise, the XPATH in the tables below is relative to: on/lineups/lineup
| XPATH Element\Attribute | Description | Example |
|---|---|---|
| @id | Gracenote unique identifier of a channel lineup. | USA-CA00056-X |
| lineupInfo/country/ | Lineup country. ISO 3166-1 alpha-3 country code | USA |
| lineupInfo/country/@countryId | Lineup country. ISO 3166-1 numeric country code | 840 |
| lineupInfo/mso/ | MSO (multiple system operator) name. | Comcast Corporation |
| lineupInfo/mso/@msoId | Unique Gracenote identifier for the MSO | 8010 |
| lineupInfo/headend/ | Name of the headend serving the channel lineup. | Xfinity |
| lineupInfo/headend/@headendId | Gracenote unique identifier of the headend. | USA-CA00056 |
| lineupInfo/location/ | City name of the headend location. | South San Francisco |
| lineupInfo/device/ | Gracenote device type name of channel lineup. | Digital (non-rebuild) |
| lineupInfo/device/@type | Gracenote device type letter code of channel lineup. | X |
| lineupInfo/type/ | Gracenote lineup service type. | CABLE |
| lineupInfo/markets/market/ | Nielsen name of an individual market. | San Francisco-Oak-San Jose |
| lineupInfo/markets/market/@type | Nielsen market type. | DMA |
| lineupInfo/markets/market/@marketId | Nielsen market numeric code. | 807 |
| lineupInfo/postalCodes/postalCode/ | Individual country postal code(s) where this lineup is available. | 94014 |
Lineup Types
Channel Lineups are available for the following types of video distribution services. Not all lineup types are present in all countries:
| Lineup Type | Description |
|---|---|
| OTA | Over-the-air terrestrial lineup for analog broadcast stations. |
| DIGITAL | Over-the-air terrestrial lineup for digital broadcast stations (US/Canada) |
| DIGITAL_BROADCAST | Over-the-air terrestrial lineup for digital broadcast stations (outside of US/Canada) |
| CABLE | Lineup for service delivered by coaxial or fiber-optic cable. |
| SATELLITE | Lineup for direct-to-home satellite service. |
| IPTV | Lineup delivered over the internet via a privately-managed network. |
| OTT | Lineup delivered over open internet, for example for virtual MVPD "skinny bundle" linear channels |
| VIRTUAL | Gracenote provides a set of two virtual lineups for a subset of countries: a) Virtual country lineup (lineup name = country name) represents the most watched channels in country based on market share. b) Extended country lineup (lineup name = country name + "(extended)" in local language) represents a superset of all channels included in lineups of any other lineup type for given country |
Specific channel lineup types (CABLE, SATELLITE, OTT) can also have an end user device type designation. The device type indicates the specific video service type of the lineup. e.g. “Cable/Digital Rebuild”.
Channel List
Unless stated otherwise, the XPATH in the table below is relative to: on/lineups/lineup/channelList/channel/
| XPATH Element\Attribute | Description | Example |
|---|---|---|
| @prgSvcId | Gracenote unique identifier for the station (programming service) | 96335 |
| channelNumber/ | Channel position number of the station in the lineup | 017 |
| channelNumber/@effectiveDate | Date that the channel at a specific dial position becomes active | 2024-05-15 |
| channelNumber/@expirationDate | Date that the channel at a specific dial position becomes inactive | 2024-07-31 |
| channelNumber/@tier | One of five levels of service (not a subscriber package) | 1 |
Channel lineups are updated at a cadence appropriate for the market, lineup type, and provider. Updates can be on demand when sent by the provider, or once a month, or every three months etc. Channels that are added or deleted may be indicated by the effectiveDate and expirationDate attributes.
The same station can be present in the lineup on multiple channel positions. This is by design as providers typically have the same channel in multiple tiers and packages.
Channel tiers is a legacy construct that attempted to group stations by high level service groups. Tiers are not subscription packages - please refer to the Supplemental Controlled Vocabulary (auto-download) for tier definition.
Channel Transport Identifiers
| XPATH Element\Attribute | Description | Example |
|---|---|---|
| transportIds/transportId/system/ | Transport id system | DVB |
| transportIds/transportId/subSystem/ | Transport id sub-system | DVB-C |
| transportIds/transportId/idParts/idPart/id/ | Transport id type | ONID, TSID, SID |
| transportIds/transportId/idParts/idPart/type/ | Transport id value | 9999, 411, 41101 |
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 DVB transports ids in certain EU countries and Australia at the lineup channel level. The DVB transport ids are composed of three distinct ID parts (ONID, TSID, SID) and are also referred to as DVB triplets.