Frequently Asked Questions
This section answers frequently-asked questions (FAQs).
General
Do you support HTTPS requests?
Clients can make calls via HTTP or HTTPS. No additional configuration is required for SSL.
Getting Updates
What is the maximum allowable limit to retrieve objects across all GVD API endpoints?
Gracenote recommends a maximum limit of 1000 across all endpoints except Lineups. The maximum allowable limit for the Lineups endpoint is 10. This means any API queries for the Lineups endpoints requesting more than 10 objects will automatically be throttled to return 10 objects.
How do we get an initial set of GVD seed files?
There are two ways to get an initial seed dataset:
- Use the GVD API to make single-threaded, sequential requests based on the last updateId received. See Getting Updates
- Import weekly seed files from the Gracenote FTP site. Then, use updateIds with GVD API to get the latest updates. For more information about obtaining seed files, see Getting Initial Data and Updates
Can I make multi-threaded requests to the API using different updateId ranges to get an initial seed dataset?
We do not currently provide a means to partition updateId ranges for seeding purposes. This is being considered as a future roadmap item. Current seeding requires single-threaded, sequential requests based on the last updateId received.
Are update tokens (updateId) assigned per method, or across all methods?
The updateId token is unique per method. The last updateId received should be stored per method for delta retrievals. Sample storage of updateId:
| Entity | Max updateId received |
|---|---|
| Programs | 20248923 |
| Schedules | 49275382 |
| Sources | 3029384 |
| Celebrities | 12048273 |
| ProgramMappings | 287077806 |
How and when are additional schedule days added to my Schedules dataset?
A daily process runs at midnight UTC to add one additional schedule day per station to your dataset. You will see a batch of updates at that time corresponding to the additional schedule days. This daily process ensures that you can use a continuous process to pull both editorial updates and new schedules days using same updateId.
What does updateDate mean? Can I use it to get deltas since a certain timestamp?
The updateDate is included for informational purposes only, and represents the timestamp the entity was updated or became available to the customer dataset. For instance, when new schedule days become available shortly after midnight UTC each day, they are marked with updateDate at that point to indicate when they were assigned new updateIds for retrieval. Any subsequent updates to those schedule days will receive a new updateId and updateDate. The updateDate is not available as a request parameter.
How can I tell when I received all available updates?
When a response no longer has a nextUpdateId, or the maxUpdateId is the same as the updateId value, a query based on most recent updateId returns no objects. This indicates that all available updates were received.
If your system is polling for new updates, the response will contain no objects if there are no new updates available. Also, the maxUpdateId in the streamData object will match your updateId value.
How are customers charged for excess Media Cloud usage?
The fee is inclusive of 2 TBs On Connect Media Cloud transactions per month. An additional fee will be charged for transactions that exceed the default 2TB, in increments of 1 TB.
Deleted/DNU (Do Not Use) Data
Content that is invalid, no longer part of GVD, and are candidates for a hard delete are marked as deleted object. These are flagged as <deleted>true</deleted>. This also means that the GNID will no longer get any updates (via update_id) in the API. Applies to all GVD endpoints.
Code
Where:
<deleted>true</deleted>implies the document is no longer valid, to be deleted from the system.<inactive>true</inactive>implies the document is no longer part of customer entitlement.
Processing Data
Programs
What precedence should we follow to pick the right parental rating for a Program Context?
Depending on the market, the following precedence is recommended.
- Ratings in Catalog item: Most accurate rating applicable to a TV program when available.
- Rating in Program record
Example: Canadian Rating
We recommend CPR (Canadian Parental Rating) rating body for English programs in Canada. GVD Rating body: RTG_CAN_15 holding rating values such as C, C8, G, PG, 14+, 18+.
Régie du cinéma (Québec) is rating body used by TV broadcasters for French programs in Canada when available. Rating body RTG_CAN_09 is most applicable to edit / description language of the program i.e., fr_CA. If unavailable, we fallback to other rating bodies.
How is a GNID for a GVD object created?
Every object in GVD such as a Source, Program, and so on, consist of a unique alphanumeric ID generated based on triplet consisting of:
- id_type
- vendor(supplier) system
- id
For example: A Program triplet tms_id | tms | MV005894820000 generates a unique GNID, such as GNEQZNGPP33N2ST.
I am seeing a Program record with multiple MAIN titles. Which one do I pick?
Pick the title that is relevant to the program type. GVD renders both episodic title as well as the parent program title within the same title block of a program. Below are descriptions for each title type and subtype with examples. See Working with Program Titles.
Working with Schemas
Where can we find the Controlled Vocabulary (CV) and is it available in XML / JSON?
GVD has a controlled vocabulary endpoint in XML that has description and examples. For example: Rating_Subtype | RTG_USA_01_01 | Rating value: G, Rating body: MPAA (USA).
The CV is available as a downloadable endpoint. See Data Dictionaries and Controlled Vocabulary for more information.
What do we mean by Catalog object and its Manifest?
A Catalog object consists of information such as schedule qualifiers, video quality (HD, UHD, ...), audio quality ( DOLBY, ...), pricing options available, and so on, that associate to a program record. Catalog object serves two use cases:
- Give me all US schedules.
- Where can I watch the latest episode of Big Bang Theory? In an EPG schedule or a VOD catalog?
Manifest lists all the catalog items associated to a source. For example: All programs for CNN.
Where can I find related channels in GVD?
Affiliate block in the Sources endpoint consists of source relations such as:
- Parent network
- Time Zone Sibling of
- HD Version of
- Digital Version of
- UHD Version of
- Digital Sibling of
How are schema updates communicated?
Schema updates are a part of GVD release planning. GVD customers are notified in advance of any potential schema changes.
Note: The schema version is not the same as the GVD product version. For example, the current GVD version is 3.0.5.
You can determine the schema version by looking at the xsd updates file: gvd_updates_<version>.
For example, gvd_updates_3.0.5 indicates the GVD schema version number is 3.0.5. See the example below.
Code
Note: In the example above,
schemaVersion="1.0"refers to the XML Standard Schema version, not the GVD schema version.
Where can I find traditional Schedule qualifiers such as SAP, CC, Premiere, Live, First Airing, etc. in GVD?
Schedule qualifiers are available in Catalog Item object endpoint as qualifier_type and qualifier_subtype (when applicable). These are NOT available in the Availability Day (Schedule) endpoint. They are grouped as catalog-level metadata alongside VOD qualifiers such as HD, DOLBY, 4K, etc.
XPath:
Code