Schedules Endpoint
The Schedules endpoint is designed to retrieve Gracenote TV schedules, organized by station identifier (programming service ID, or prgSvcId) and UTC datetime.
The Schedules schema provides timeslot-level information, including:
- prgSvcId, for linking to station details in Sources API
- TMSId, for language-specific representation of program on schedule
- Datetime, specified in UTC for simple conversion to display timezones
- Schedule ratings, from ratings boards in airing area, if available
- Content rights, to support client specific use cases such as Instant Restart, User Recordings, Mobile Viewing
- Additional timeslot qualifiers, such as CC, HDTV, Live
All schedule days are marked with a unique updateId, denoting current information for station’s schedule on that date. Changes to any timeslot within the 24-hour schedule day will result in assignment of a new updateId, which allows you to pull deltas since last retrieval of schedule information. Scope of schedules can be requested by subset of stations in particular country, lineup, or custom station list, and a consistent window of schedule day updates is continuously available for request. For example, customers who choose to receive 21-days of schedules for US and Canadian stations will receive a continuous stream of updates, with new schedule days and stations automatically added to the stream of updates.
Schedules Endpoint Data Structure and Relationships
Schedules 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_schedules_3.22.xsd
The following tables list key data elements of the Schedules endpoint. Unless stated otherwise, the XPATH in the tables below is relative to on/schedules/schedule/
Identifiers
| XPATH Element/Attribute | Description | ID Space |
|---|---|---|
| @prgSvcId | Gracenote unique identifier for the station/programming service | prgSvcId |
| @date | Air date in YYYY-MM-DD format, UTC | - |
Timeslot / Event Data
Ratings
Parental rating is an optional element of an event. The airing ratings are provided to Gracenote by sources and may or may not be present. Programs may have their own (Gracenote-curated) parental ratings which can be used as a fallback.
| XPATH Element/Attribute | Description | Example |
|---|---|---|
| event/tv/tvRating/ | TV parental rating for the event | TV14 |
| event/tv/tvRating/@body | The ratings body that issued the parental rating guidelines | USA Parental Rating |
For programmatic usage, the ratings bodies and warnings are enumerated in the Data Dictionaries and Controlled Vocabulary endpoint, under RatingsBody and RatingAdvisory types.
Qualifiers
Qualifiers are labels that provide additional information about the airing, such as the technical details about the format; whether this is a live airing or if it’s shown with a delay; whether it is a premiere or replay; subtitles/dubbing info etc.
Notable qualifiers are listed below. Please refer to the Supplemental Controlled Vocabulary (auto-download) for a full list of qualifiers and their definitions.
Exact Start/End Times and Duration
Exact start/end time and exact duration values are provided to Gracenote by sources and may or may not be present; they are exposed as available for entitled clients. These fields identify when a linear program truly aired and how long it aired for. The values may be different from the published start time and duration of the program.
| XPATH Element/Attribute | Description | Example |
|---|---|---|
| event/@exactStart | Source-provided exact start time of a scheduled event | 01:27:08 |
| event/@exactDur | Source-provided exact duration of a scheduled event | PT01H26M14S |
| event/@exactSource | The source of the exact time information | Broadcaster |
| event/@exactStartDateTime | The exact start datetime of a program in UTC | 2024-07-20T01:27:08Z |
| event/@exactEndDateTime | The exact end datetime of a program in UTC | 2024-07-20T02:53:22Z |
Broadcast Identifiers
Broadcast ids (also can be referred to as Remote / Source / Provider ids) are identifiers that Gracenote receives from its linear schedule providers. These identifiers are typically used for matching Gracenote data to provider data, they can be of different types (e.g. program, event, series etc), the types vary depending on the provider. Broadcast Identifiers are optional and exposed as available, some are available by entitlement.
| XPATH Element/Attribute | Description | Example |
|---|---|---|
| event/broadcast/id/ | Broadcaster-specific identifier for the event | 2679283, 200090296, 422390 |
| event/broadcast/id/@type | Broadcast identifier type | remoteId, remoteSeriesId, remoteEventId |
Referenced CV Lists
The following Schedules value lists are enumerated in the Data Dictionaries and Controlled Vocabulary Endpoint:
- Ratings
The following Schedules value lists are documented in the Supplemental Controlled Vocabulary (auto-download):
- Qualifiers
Entity Relationship Diagram
The following diagram illustrates the references from a schedule record to other objects within the On API.
API and Example Responses
API
http://on-api.gracenote.com/v3/Schedules ?updateId=[updateId value] &limit=[limit value] &api_key=[your-api-key]
Request Parameters
Important: Use lookup calls for QA and troubleshooting purposes only. Gracenote does not support lookup APIs for Client production environments.
Example Requests
Return schedules updated since last delta request, in batches of 1000 station days.
http://on-api.gracenote.com/v3/Schedules?updateId=2948902&limit=1000&api_key=<your-api-key>
Return full schedules for two stations for specified 10 day window.
http://on-api.gracenote.com/v3/Schedules?prgSvcId=10098,10003&startDate=2017-05-01&endDate=2017-05-11&api_key=<your-api-key>
Note: Only stations and dates within a configured customer stream are returned. For example, customers receiving 21-day schedules for stations in USA/CAN lineups can request any schedule within that range. Any requested stations or dates outside configured range are not included in a response.
Example Responses
Also see: Schedules XML examples
Schedules Updates
You can retrieve schedules using:
- updateId - Unique update token, used to retrieve schedules modified since last request, sequenced by updateId. Can be combined with limit to ingest specified batch size
- prgSvcId and date range -Retrieve specific schedule records, sequenced by prgSvcId and date. To be used for evaluation and troubleshooting purposes, not programmatic ingestion
When API is used in ‘lookup’ mode using prgSvcId and date range, requests for schedule data outside the pre-configured station list and schedule window will not be retrievable. Only schedules within customer station list and schedule window are returned. To modify pre-configured station list or schedule window, contact your Gracenote representative to modify your configuration.
The most granular update block within schedule data is the station day (prgSvcId + date). Schedules are included on day in which event started. For timeslots which cross date boundary (for example, a show which begins at 23:00 and ends at 01:00 next day), the schedule will always appear within station day corresponding to schedule start time.
Automatic extension of stream date range will occur daily at midnight UTC. A full set of additional station days are assigned updateIds and become available in update result sets.
Updates are returned in 24-hour blocks. Individual timeslots are not marked with any update indicator . Entire daily station schedule in user datastore should be overlaid with newly updated data.
Automatic Updates to Station List and Schedule Window
The pre-configured station list is automatically updated to include new stations when they are either added to, or become eligible for, the custom update stream. Existing stations may become eligible for custom update stream if they newly meet filter criteria defined on customer requirements (for example, new station appears on lineup).
Schedules for the newly added/eligible stations are automatically seeded (assigned new consecutive updateIds) and received as normal updates within Schedule Update processing. When stations are removed or fall out of pre-configured station criteria, Schedules API will not include ‘deleted’ indicator, but will no longer issue updates for the station, and the removed stations will not be returned in lookups.
Similarly, the pre-configured schedule window (for example, 7-days, 14-days, etc) will also be automatically handled with new updateIds assigned to schedules (station days) as they cross into the eligible schedule window.
Note: Updates to schedules within pre-configured date range is included. For example, on a 7-day schedule stream, with 1-day buffer on each end, API calls on 5/10/2025 will return updated schedules from 5/9/2025 through (and including) 5/17/2025. Any updates made to schedule dates prior to 5/9/2025 are excluded.
Schedules Feature Details
This section provides additional information about specific Schedules features, including response types and sample output.
Exact Start and Duration
Exact start time and exact duration values are exposed as available for entitled clients.
These fields identify when a linear program truly aired and how long it aired. The values may be different from the published start time and duration of the program.
The exact source attribute can have two different values:
- Broadcaster: These are the exact start and duration values provided by the source (broadcaster) to Gracenote.
- Media Distillery: These are the exact start and duration values provided by an EPG correction service. This is an additional service available from Gracenote.
If you are entitled to Media Distillery data, Media Distillery data overwrites Broadcaster provided data if both are available on a channel.
The sample data below has both Broadcaster and Media Distillery data.
Content Rights
Content Rights (or Usage Rights), Content Flags, Content Restrictions, Usage Restrictions or sometimes Blackouts - represent a piece of metadata attached to linear TV schedule events related to the content availability for different use cases on the target distribution platform. The Content Rights are usually specific to one distribution platform, whether it be an MVPD’s service or a D2C streaming service, and describe what broadcasters or content owners allow the platform to do with events appearing in the linear TV programming.