Using the GVD API Explorer

Gracenote provides an API Explorer you can use to view and navigate GVD data:

  1. Go to  http://developer.tmsapi.com/
  2. Click on the API Explorer tab.
  3. Use the Select an API dropdown to navigate to the GVD APIs.

Note: To access the GVD APIs, you need an API Key. Contact your Gracenote representative to get one. You will also need this key to use to the Gracenote API Explorer. You can use the explorer to try out the APIs in real time.

API Summary

The following table summarizes the Endpoints that are available on the Gracenote portal.

 

Endpoint API URL
Availability Day http://gvd-api.gracenote.com/v1/availabilityday?<external_parameters>
Availability Day Manifest http://gvd-api.gracenote.com/v1/availabilityday/manifest?<external_parameters>
Catalog Item http://gvd-api.gracenote.com/v1/catalog/item?<external_parameters>
Catalog Manifest http://gvd-api.gracenote.com/v1/catalog/manifest?<external_parameters>
Contributor http://gvd-api.gracenote.com/v1/contributor?<external_parameters>
Controlled Vocabulary http://gvd-api.gracenote.com/v1/cv?<external_parameters>
Country http://gvd-api.gracenote.com/v1/country?<external_parameters>
Lineups http://gvd-api.gracenote.com/v1/lineup?<external_parameters>
Media http://gvd-api.gracenote.com/v1/media?<external_parameters>
Programs http://gvd-api.gracenote.com/v1/programs?<external_parameters>
Program Presentation Endpoint http://gvd-api.gracenote.com/v1/program_presentation?<external_parameters>
Sources http://gvd-api.gracenote.com/v1/sources?<external_parameters>
Video Descriptor Taxonomy Items http://gvd-api.gracenote.com/v1/videodescriptortaxonomyitems?<external_parameters>
Video Popularity http://gvd-api.gracenote.com/v1/video_popularity?<external_parameters>

Availability Day API

v1/availabilityday

Returns Availability Day objects that are delivered by the entitlement. These provide schedule driven data for channels

Parameter Value Type Description
updateId 0 string

Returns Availability Day objects modified at or after updateId. Get the value for updateId from the update_id value in the dataset. Use this Idwith the limit parameter for handling batches of updates
limit 10 string

Approximate maximum number of Availability Day objects to be returned by API; to be used in conjunction with updateId for handling batches of updates
id   string Used for a lookup of a direct Availability Day object by its Gracenote ID. Use Lookup calls for QA/troubleshooting purposes only. Gracenote does not support lookup APIs for Client production environments.
api_key   string Gracenote API Key

Availability Day Manifest API

v1/availabilityday/manifest

Returns Availability Day Manifests objects that are delivered by the entitlement. These objects reference Availability Day objects to help create 14+ day EPG schedules

Parameter Value Type Description
updateId 0 string

Returns Availability Day Manifest objects modified at or after updateId. Get the value for updateId from the update_id value in the dataset. Use this Idwith the limit parameter for handling batches of updates
limit 10 string

Approximate maximum number of Availability Day Manifest objects to be returned by API; to be used in conjunction with updateId for handling batches of updates
id   string Used for a lookup of a direct Availability Day Manifest object by its Gracenote ID.Use Lookup calls for QA/troubleshooting purposes only. Gracenote does not support lookup APIs for Client production environments.
api_key   string Gracenote API Key

Catalog Item API

v1/catalog/item

Returns Catalog Item objects which are delivered by the entitlement.

Parameter Value Type Description
updateId 0 string

Returns Catalog Item objects modified at or after updateId. Get the value for updateId from the update_id value in the dataset. Use this Idwith the limit parameter for handling batches of updates
limit 10 string

Approximate maximum number of Catalog Items objects to be returned by API; to be used in conjunction with updateId for handling batches of updates
id   string Used for a lookup of a direct Catalog Items object by its Gracenote ID. Use Lookup calls for QA/troubleshooting purposes only. Gracenote does not support lookup APIs for Client production environments.
api_key   string Gracenote API Key

Catalog Manifest API

v1/catalog/manifest

Returns Catalog Manifest objects that are delivered by the entitlement.

Parameter Value Type Description
updateId 0 string

Returns Catalog Manifest objects modified at or after updateId. Get the value for updateId from the update_id value in the dataset. Use this Idwith the limit parameter for handling batches of updates
limit 10 string

Approximate maximum number of Catalog Manifest objects to be returned by API; to be used in conjunction with updateId for handling batches of updates
id   string Used for a lookup of a direct Catalog Manifest object by its Gracenote ID. Use Lookup calls for QA/troubleshooting purposes only. Gracenote does not support lookup APIs for Client production environments.
api_key   string Gracenote API Key

Contributor API

v1/contributor

Returns Contributor objects that are delivered by the entitlement.

Parameter Value Type Description
updateId 0 string

Returns Contributor objects modified at or after updateId. Get the value for updateId from the update_id value in the dataset. Use this Idwith the limit parameter for handling batches of updates
limit 10 string

Approximate maximum number of Contributor objects to be returned by API; to be used in conjunction with updateId for handling batches of updates
id   string Used for a lookup of a direct Contributor object by its Gracenote ID.. Use Lookup calls for QA/troubleshooting purposes only. Gracenote does not support lookup APIs for Client production environments.
api_key   string Gracenote API Key

Controlled Vocabulary API

v1/cv

Returns the Controlled Vocabulary for Global Video Data.

Parameter

Value

Type

Description
updateId 0 string

Returns a Controlled Vocabulary object modified at or after updateId with all of the CV in a single object
limit 10 string

Approximate maximum number of a CV object to be returned by API; frequently should be 1
id

 

 string Used for a lookup of a direct CV object by its Gracenote ID. Use Lookup calls for QA/troubleshooting purposes only. Gracenote does not support lookup APIs for Client production environments.
api_key

 

 string Gracenote API Key

Country API

v1/country

Returns Country objects that cover the line ups, sources and program contexts available in a country

Parameter

Value

Type

Description
updateId 0 string

Returns Country objects modified at or after updateId. Get the value for updateId from the update_id value in the dataset. Use this Idwith the limit parameter for handling batches of updates
limit 10 string

Approximate maximum number of Country objects to be returned by API; to be used in conjunction with updateId for handling batches of updates
id   string Used for a lookup of a direct Country object by its Gracenote ID. Use Lookup calls for QA/troubleshooting purposes only. Gracenote does not support lookup APIs for Client production environments.
api_key   string Gracenote API Key

Lineups API

v1/lineup

Returns lineup_provider objects that are delivered by the entitlement.

Parameter Value Type Description
updateId 0 string

Returns lineup_provider objects modified at or after updateId. Get the value for updateId from the update_id value in the dataset. Use this Idwith the limit parameter for handling batches of updates
limit 10 string

Approximate maximum number of lineup_provider objects to be returned by API; to be used in conjunction with updateId for handling batches of updates
id   string Used for a lookup of a direct lineup_provider object by its Gracenote ID. Use Lookup calls for QA/troubleshooting purposes only. Gracenote does not support lookup APIs for Client production environments.
api_key   string Gracenote API Key

Media API

v1/media

Returns Media objects which are delivered by the entitlement.

Parameter Value Type Description
updateId 0 string

Returns Media objects modified at or after updateId. Get the value for updateId from the update_id value in the dataset. Use this Idwith the limit parameter for handling batches of updates
limit 10 string

Approximate maximum number of Media objects to be returned by API; to be used in conjunction with updateId for handling batches of updates
id   string Used for a lookup of a direct Media object by its Gracenote ID
api_key   string Gracenote API Key

Programs API

v1/programs

Returns entitled programs data. Use either updateId and limit for update mode, id to use the API as a lookup API.

Parameter Value Type Description
updateId 0 string

Returns programs modified at or after updateId. Get the value for updateId from the update_id value in the dataset. Use this Idwith the limit parameter for handling batches of updated programs
limit 10 string

Approximate maximum number of programs to be returned by API; response will send all contexts for a root program, ending when GNID count is at or over limit count; to be used in conjunction with updateId for handling batches of program updates
id   string Used for a lookup of a direct Program object by its Gracenote ID. Use Lookup calls for QA/troubleshooting purposes only. Gracenote does not support lookup APIs for Client production environments.
api_key   string Gracenote API Key

Sources API

v1/sources

Returns Source objects that are delivered by the entitlement.

Parameter Value Type Description
updateId 0 string

Returns Source objects modified at or after updateId. Get the value for updateId from the update_id value in the dataset. Use this Idwith the limit parameter for handling batches of updates
limit 10 string

Approximate maximum number of Source objects to be returned by API; to be used in conjunction with updateId for handling batches of updates
id   string Used for a lookup of a direct Source object by its Gracenote ID
api_key   string Gracenote API Key

Video Descriptor Taxonomy Items API

v1/videodescriptortaxonomyitems

Returns the hierarchical taxonomy for Video Descriptors, grouped by Taxonomy Items (aka Video Descriptor Type). Each Video Descriptor Type is considered one object and is available as a Video Descriptor Taxonomy Item. The Video Descriptors feature is sold separately. Contact your Gracenote representative to get this feature.

Parameter Value Type Description
updateId   string

Returns full snapshot of Video Descriptors that belong to a Taxonomy Item (aka Video Descriptor Type), modified at or after updateId. Individual Video descriptors updates are not published independently

limit   string

Maximum number of a Video Descriptor Taxonomy Items to be returned by the API

Id   string

Used for a lookup of all Video descriptors that belong to a single Taxonomy Item (aka Video Descriptor Type). Example all descriptors under Scenario (id = GN0FYAPK8TW10ZF)

api_key   string Gracenote API Key

Video Popularity API

Gracenote Video Popularity assigns a numeric score to TV series and movies, which indicates the majority of the population's level of recognition of a video program.

v1/video-popularity

Parameter Value Type Description
updateId   string

Returns full snapshot of video popularity modified at or after updateId.

limit   string

Maximum number of a video-popularity items to be returned by the API

program_root_id   string

GN root id for the program. The main id associated with the score for a given day. All GN context ids associated with a GN root id will have the same score for a given country. Use Lookup calls for QA/troubleshooting purposes only. Gracenote does not support lookup APIs for Client production environments.

api_key   string Gracenote API Key