Building a Programs Database

Use Case 1: Extracting Programs in TV Channel Schedules

Note: For instructional purposes, the use cases described below use GVD API queries to retrieve and navigate data. For real-world applications, you should populate your databases using the instructions in Getting Seed Data and Updates and map primary database keys to IDs based on instructions in Mapping GNIDs to Primary Database Keys. Then use standard database queries to retrieve and navigate GVD data.

Also, the GNIDs used in this use case are for explanation only. They may change if the element becomes inactive or is deleted.

Process

Below are the steps recommended to extract programs (top-down approach).

1. Extract Country Lineups

Extract all the lineups available for a given Country in the Country XML.

Example: GN9169P75VY1R3R

Code
 
http://gvd-api.gracenote.com/v1/country?id=GN9169P75VY1R3R&api_key=<customer_key>

2. Get Sources from Lineup

The sources (channels) for each lineup are listed in the Lineup XML. They are specific to a location – area, city/county/town, and state.

Example: GN10JSWZGAXTFCB

Code
 
http://gvd-api.gracenote.com/v1/lineup?id=GN10JSWZGAXTFCB&api_key=<customer_key>

3. Access TV Schedules

For each channel (about 800+ in India), the TV schedules are available in Availability Day (AD) endpoint. All the latest schedules (10-14 days) IDs are available in Availability Manifest (AM) Endpoint.

Example:

Source: GN542Z412VW9VAZ

Code
 
http://gvd-api.gracenote.com/v1/sources?id=GN542Z412VW9VAZ&api_key=<customer_key>

AM:

Code
 
http://gvd-api.gracenote.com/v1/availabilityday/manifest?id=GNDGNCZAPE04AR6&api_key=<customer_key>

4. Retrieve Schedule Data

For a given channel, typically Schedules (AD) point to programs for a 24-hour TV grid. In GVD, schedules point to Catalog Items (CI) instead.

Example: GN8KASCZB5JGC0J

Code
 
http://gvd-api.gracenote.com/v1/availabilityday?id=GN8KASCZB5JGC0J&api_key=<customer_key>

5. Access Catalog Items

Catalog Items are programs specific to a source. In other words, if a program is available in multiple channels or VOD sources, it is treated as a separate entity in Catalog Item XML. A list of such catalog items for a Source constitutes a Catalog Manifest (CM).

Example: A Program "3 Idiots" appeared in multiple catalogs.

• Program GNID: GNC1R7DTQ5KDRGQ
• Program Context GNID: GN70PNMFMN6V3JE

Code
 
http://gvd-api.gracenote.com/v1/programs?id=GNC1R7DTQ5KDRGQ&api_key=<customer_key>

Source 1 GNID: GN815CW4XF7KZRR

Code
 
http://gvd-api.gracenote.com/v1/sources?id=GN815CW4XF7KZRR&api_key=<customer_key>

Source 2 GNID: GNDBQY7HPKG76VD

Code
 
http://gvd-api.gracenote.com/v1/sources?id=GNDBQY7HPKG76VD&api_key=<customer_key>

6. Retrieve Program Metadata

Every Catalog item points to a single program context that is relevant to the Source. The programs metadata is available in Program XML.

Example:

• Program GNID: GNC1R7DTQ5KDRGQ
• Program Context GNID: GN70PNMFMN6V3JE

Code
 
http://gvd-api.gracenote.com/v1/programs?id=GNC1R7DTQ5KDRGQ&api_key=<customer_key>

7. Access Media and Contributors

All program images, cast and crew for the above programs are available in Media and Contributor XML endpoints respectively. Similarly, Cast/Crew imagery can be located in Media endpoint.

Example: Contributor Aamir Khan (GN7D5ZY0527JNZY) associated to program "3 Idiots" (GNC1R7DTQ5KDRGQ)

Code
 
http://gvd-api.gracenote.com/v1/contributor?id=GN7D5ZY0527JNZY&api_key=<customer_key>