GVD includes a powerful set of data delivery APIs designed to ingest large amounts of metadata into your Content Delivery Network. Using these APIs, you can build a Service Delivery Platform (SDP) to deliver current and relevant data to end-user devices. To get GVD data updates, follow the processes described in these sections.
Getting Initial Data and Updates
GVD is a set of streaming API endpoints to stay up to date with the latest data. Gracenote assigns each customer their own data stream containing only the data pertinent to their subscription. Anytime a change is made on any of the GVD endpoints, an incremental updateID is assigned. You can keep your data up to date by periodically querying for updates that have occurred since the last ingested updateID. Each GVD endpoint response includes a nextUpdateId field and a maxUpdateId field. Use the nextUpdateId field to start your next update query. Use the maxUpdateId field to determine when to stop the query. The maxUpdateId specifies the maximum updateId available for the specific endpoint at the time the response was provided to the client. It is possible that this is not the actual maximum updateId as new updates can continue to flow in. Important: Due to the large volume of data entitlements, Gracenote engineering has enabled a limit parameter to control batch size of each request. We recommend ingesting with a limit of 1000 records per query across all endpoints except Lineups. The maximum allowable limit for the Lineups endpoint is 10. We do our best to optimize the API for all of our global customers. However, if you encounter performance issues like the response taking too long, or not getting a response at all, we recommend retrying with a reduced batch size.
Update Process
- To get initial seed data, use GVD with a request parameter of updateId=0.
- Schedule update requests hourly, or in whatever time increment you need for your application. For each iteration, use the nextUpdateId to receive the next dataset.
- Use the limit parameter to control ingestion batch size. (10 recommended for Lineups, 1000 recommended for all other endpoints)
- Iterate until no further updates are returned. To do this, test if the maxUpdateId matches the value of the updateId in the request. Another way to confirm there are no more updates is if the nextUpdateId is missing in the response. If there are no further updates available, nextUpdateId will not exist in the response.
- You can restart ingestion at any point by reverting to an earlier updateId*, or reseeding data from updateId=0*.
Endpoint Update Sequence
After you have seeded all endpoint data, and are caught up with the latest data using updateId for each endpoint, follow the sequence below to receive regular updates:
- Programs
- Sources
- Schedules
- Celebrities
- Sports-related (Teams, Venues, Organizations, Universities)
Endpoint Update Frequency
Data is continuously being added and updated to the Gracenote database and made available via GVD. The metrics below are for general guidance purposes and are based on past experience of data flow, but more or less data may be observed at any time, given operational and editorial activities. You should plan for potential spikes in data output and for the potential of no available updates during some time periods. Note that the metrics below are based on delivery of updates after receiving an initial full dataset for North American (USA+CAN) schedule data
| Entity | Daily Average | High |
|---|---|---|
| Sources | 175 | 300 |
| Celebrities | 1,500 | 5,000 |
| Schedules* | 120,000 | 250,000 |
| Programs | 150,000 | 400,000 |
- Schedule updates are delivered based on station+day:
- At midnight UTC, one full new day is delivered for each channel to extend the schedule window.
- Typical mid-day editorial schedule updates are delivered throughout the day as they occur.
- Due to the nature of schedule updates, frequency of updates will vary based your dataset.
Data Recovery
In cases of complete data loss, you can restart ingestion from updateId=0. The GVD data stream only maintains the newest (highest updateId) version of an object, so you will not be streaming through every historical update. However, this data refresh can be a lengthy process. In the event that ingestion stopped, but existing data was maintained, you can resume ingestion based on your last known update ID. If you do not know the last updateId used, you can instead use a date/time parameter to restart ingestion and then switch back to using update IDs.
Handling Deleted and Inactive Endpoint Records
GVD uses two attributes to indicate when a record is not available:
deleted=trueinactive=true
Your client code should handle these instances as described below:
| Endpoint | Parameter |
|---|---|
| Celebrities | deleted="true" |
| ProgramMappings | deleted="true" |
| ProgramAvailabilities | deleted="true" |
| Programs | deleted="true", inactive="true" |
| Sources | deleted="true", inactive="true" |
| Schedules | This endpoint does not use these attributes. It updates for a full 24-hour channel day. |
| Video Descriptors Taxonomy | This endpoint does not use deleted or inactive attributes |
The attributes "deleted" and "inactive" represent the following scenarios and actions:
| Parameter | Description |
|---|---|
| deleted="true" | Record and ID has been deprecated from Gracenote's database. You should not use this record. Remove from your database or retain but marked as "deleted" and not for use. |
| inactive="true" | Record is not currently in your API entitlement. For Source records, it indicates that the station and schedules have been removed from the entitlement. You can remove from your database or retain but marked as "inactive" and not for use. For Programs records, it indicates that the program record is: Not in window and not referenced in Schedules; Not in window and not referenced in ProgramMapping; Has been manually removed from the client's entitlement by Gracenote for other cases and means. You can remove from your database or retain but marked as "inactive" and not for use. |
Note: When the program is flagged as deleted, the body of the XML will still display information previously tagged for that program. The deleted program will persist in the output and will not be purged.
Getting Images and Image Updates
Image references are included in all top-level elements, with exception of Schedules and Venues.
Program Images
Program images are output at a normalized program-specific level. For TV shows, this means that series-level and season-level images will only be included on the series program record (TMS IDs beginning with SH). Series and season level images will not be repeated on each episode program record; the connectorId and seasonId on the episode should be used to link to the appropriate series/season level images. Episodes may contain their own episode-specific imagery.
Source Images
Source images include TV station logos for the station itself, or if station is a local affiliate of broadcast or cable network, the network logo is included directly on the local station record.
Celebrity Images
Celebrity images include standard headshots of celebrities. Cast in character images are not included in Celebrity record, but are found within Program record assets for TV shows, with reference to the personId for linkage between Programs and Celebrities.
Sports Images
Sports images for Organizations (leagues), Teams, and Universities represent standard logos for those entities. University logos are included once for each University and are not repeated within the Team record; college teams include a universityId reference which allows links to the appropriate university logo.
Handling Updated and Deleted Images
Image references within Celebrities, Programs, and Sources records provide attributes to indicate their status. As with other data updates, images provide an updateId attribute to help you track if an image has changed since your last update.
| Parameter | Description |
|---|---|
| "updateId" | Update token for tracking image changes. |
| "Deleted" | Standard boolean indicator for image purge/deletion following an expiration period. |
| "lastModified" | Last modified date of an image asset. For image deletions, indicates expiration date. |
| "expiredDate" | Expiration date of image. Indicates image has been deprecated and will be deleted after a preset number of days. |