The Gracenote Web API delivers a rich set of video metadata to help power interactive experiences for any connected application. It allows TV provider, channel, and program lookups, as well as text-based lookups of movies and television series.

eyeQ Web API Reference

Video Explore Web API Reference

Common Queries and Use Cases

URL

Send requests to this URL:

https://cXXXXXXX.ipg.web.cddbp.net/webapi/xml/1.0/

Where XXXXXXX is replaced with the seven characters of your client ID that precede the hyphen.

User Registration

Each call to the Gracenote service must be accompanied by a User ID. To register for a User ID, send the following query to the above URL:

<QUERIES>
  <QUERY CMD="REGISTER">
    <CLIENT>XXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</CLIENT>
  </QUERY>
</QUERIES>

This User ID should be stored and re-used for all subsequent calls to the Web API from the same application instance - if your queries are coming from a single host, you should only need a single User ID.

Channel Provider Lookup

A first step may be to find the Gracenote identifiers for all of the providers in your region. Here we lookup the providers for Davis Square in Boston.

Query:

<QUERIES>
 <LANG>eng</LANG>
 <COUNTRY>usa</COUNTRY>
 <AUTH>
  <CLIENT>XXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</CLIENT>
  <USER>XXXXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</USER>
 </AUTH>
 <QUERY CMD="TVPROVIDER_LOOKUP">
  <POSTALCODE>02144</POSTALCODE>
 </QUERY>
</QUERIES>

Response:

<RESPONSES>
 <RESPONSE STATUS="OK">
   <TVPROVIDER ORD="1">
      <GN_ID>251486833-598262CEBBC97BA28DCE980EF2701C93</GN_ID>
      <NAME>Comast Somerville</NAME>
      <PLACE>Somerville</PLACE>
      <PROVIDERTYPE>CAB</PROVIDERTYPE>
   </TVPROVIDER>
   <TVPROVIDER ORD="2">
      <GN_ID>251481168-DF8C867314CACE10B9D1B32ACC5C8CA4</GN_ID>
      <NAME>Tufts University</NAME>
      <PLACE>Somerville</PLACE>
      <PROVIDERTYPE>CAB</PROVIDERTYPE>
   </TVPROVIDER>
   <TVPROVIDER ORD="3">
      <GN_ID>320380286-B44501791AC650A36A897A9B88209556</GN_ID>
      <NAME>Local Over the Air Broadcast</NAME>
      <PROVIDERTYPE>DBC</PROVIDERTYPE>
   </TVPROVIDER>
 </RESPONSE>
</RESPONSES>

TV Channel Lookup

Once you have a provider, you can find the list of channels offered by that provider.

Query:

<QUERIES>
 <LANG>eng</LANG>
 <COUNTRY>usa</COUNTRY>
 <AUTH>
  <CLIENT>XXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</CLIENT>
  <USER>XXXXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</USER>
 </AUTH>
 <QUERY CMD="TVCHANNEL_LOOKUP">
  <MODE>TVPROVIDER</MODE>
  <GN_ID>320380286-B44501791AC650A36A897A9B88209556</GN_ID>
 </QUERY>
</QUERIES>

Response:

<RESPONSES>
 <RESPONSE STATUS="OK">
   <TVCHANNEL ORD="1">
      <GN_ID>251545958-935BCC7F5502DCD265D67EBF29B2EB2B</GN_ID>
      <NAME>WJARDT (WJAR-DT)</NAME>
      <NAME_SHORT>WJARDT</NAME_SHORT>
      <CHANNEL_NUM>10.1</CHANNEL_NUM>
      <RANK>0</RANK>
   </TVCHANNEL>
   <TVCHANNEL ORD="2">
      <GN_ID>251539584-91EC7235D9F16B5D7BB634F8DF3FA110</GN_ID>
      <NAME>WJARDT2 (WJAR-DT2)</NAME>
      <NAME_SHORT>WJARDT2</NAME_SHORT>
      <CHANNEL_NUM>10.2</CHANNEL_NUM>
      <RANK>0</RANK>
   </TVCHANNEL>
   <TVCHANNEL ORD="3">
      <GN_ID>251545931-601C4A6908198EB95AFBD5ECE01A02C3</GN_ID>
      <NAME>WPRIDT (WPRI-DT)</NAME>
      <NAME_SHORT>WPRIDT</NAME_SHORT>
      <CHANNEL_NUM>12.1</CHANNEL_NUM>
      <RANK>0</RANK>
   </TVCHANNEL>
 </RESPONSE>
</RESPONSES>

TV Grid Lookup

Use the TVGRID_LOOKUP to find the programs that are airing for a specified set of channels and duration of time. Here we look up the programs that are airing on two over-the-air stations in Boston between 4:00 PM and 5:00 PM. (Note that the times here are in GMT.)

Query:

<QUERIES>
 <LANG>eng</LANG>
 <COUNTRY>usa</COUNTRY>
 <AUTH>
  <CLIENT>XXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</CLIENT>
  <USER>XXXXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</USER>
 </AUTH>
<QUERY CMD="TVGRID_LOOKUP">
  <TVCHANNEL>
   <GN_ID>251545958-935BCC7F5502DCD265D67EBF29B2EB2B</GN_ID>
  </TVCHANNEL>
  <TVCHANNEL>
   <GN_ID>251539584-91EC7235D9F16B5D7BB634F8DF3FA110</GN_ID>
  </TVCHANNEL>
  <DATE TYPE="START">2013-04-26T18:00</DATE>
  <DATE TYPE="END">2013-04-26T19:00</DATE>
 </QUERY>
</QUERIES>

Response:

<RESPONSES>
  <RESPONSE STATUS="OK">
    <TVGRID>
      <TVPROGRAM>
        <GN_ID>338347022-0EED90CC3A653C96B7366DB3229FC8E5</GN_ID>
        <TITLE>Rachael Ray</TITLE>
        <TITLE_SUB>Makeover Mania!</TITLE_SUB>
        <LISTING>144, Makeover Mania!</LISTING>
        <DATE TYPE="PRODUCTIONEND">2013</DATE>
        <EPISODE_NUM>144</EPISODE_NUM>
        <SEASON_NUM>7</SEASON_NUM>
        <EPGPRODUCTION_TYPE ID="68048">Series</EPGPRODUCTION_TYPE>
        <IPGCATEGORY>
          <IPGCATEGORY_L1 ID="67860">Entertainment</IPGCATEGORY_L1>
          <IPGCATEGORY_L2 ID="67940">Talk show</IPGCATEGORY_L2>
        </IPGCATEGORY>
        <RANK>440000000</RANK>
        <GROUPREF>1000140512</GROUPREF>
      </TVPROGRAM>
      <TVPROGRAM>
        <GN_ID>338347665-D36605BF1D8A7CA79CBDF4A21D1C4B5D</GN_ID>
        <TITLE>The Dr. Oz Show</TITLE>
                <TITLE_SUB>Eva Longoria&apos;s Health Mission!</TITLE_SUB>
        <LISTING>145, Eva Longoria&apos;s Health Mission!</LISTING>
        <DATE TYPE="PRODUCTIONEND">2013</DATE>
        <EPISODE_NUM>145</EPISODE_NUM>
        <SEASON_NUM>4</SEASON_NUM>
        <EPGPRODUCTION_TYPE ID="68048">Series</EPGPRODUCTION_TYPE>
        <IPGCATEGORY>
          <IPGCATEGORY_L1 ID="67863">Topics / Documentary</IPGCATEGORY_L1>
          <IPGCATEGORY_L2 ID="67981">Health &amp; Wellness</IPGCATEGORY_L2>
        </IPGCATEGORY>
        <IPGCATEGORY>
          <IPGCATEGORY_L1 ID="67857">TV Series</IPGCATEGORY_L1>
          <IPGCATEGORY_L2 ID="67864">Other</IPGCATEGORY_L2>
        </IPGCATEGORY>
        <RANK>460000000</RANK>
        <GROUPREF>1000143330</GROUPREF>
      </TVPROGRAM>
      <TVAIRING TVCHANNEL_GN_ID="251545958-935BCC7F5502DCD265D67EBF29B2EB2B" TVPROGRAM_GN_ID="338347022-0EED90CC3A653C96B7366DB3229FC8E5" START="2013-04-26T18:00" END="2013-04-26T19:00">
        <RATING>
          <SYSTEM>FCC-TVPG (USA)</SYSTEM>
          <CODE>TV-G</CODE>
        </RATING>
        <EPGCAPTION_TYPE ID="68024"></EPGCAPTION_TYPE>
        <EPGAUDIO_TYPE ID="68004"></EPGAUDIO_TYPE>
        <EPGVIDEO_TYPE ID="68014"></EPGVIDEO_TYPE>
      </TVAIRING>
      <TVAIRING TVCHANNEL_GN_ID="251545958-935BCC7F5502DCD265D67EBF29B2EB2B" TVPROGRAM_GN_ID="338347665-D36605BF1D8A7CA79CBDF4A21D1C4B5D" START="2013-04-26T19:00" END="2013-04-26T20:00">
        <RATING>
          <SYSTEM>FCC-TVPG (USA)</SYSTEM>
          <CODE>TV-PG</CODE>
        </RATING>
        <EPGCAPTION_TYPE ID="68024"></EPGCAPTION_TYPE>
        <EPGAUDIO_TYPE ID="68004"></EPGAUDIO_TYPE>
        <EPGVIDEO_TYPE ID="68014"></EPGVIDEO_TYPE>
      </TVAIRING>
      <RANGE>
        <COUNT>2</COUNT>
        <START>1</START>
        <END>2</END>
      </RANGE>
    </TVGRID>
  </RESPONSE>
</RESPONSES>

Basic Text Search

If you want to find out more information about a specific program or movie, you can look at the Video Explore Web API docs. This example shows a basic text search using a movie title to find the associated metadata.

Query:

<QUERIES>
 <LANG>eng</LANG>
 <COUNTRY>usa</COUNTRY>
 <AUTH>
  <CLIENT>XXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</CLIENT>
  <USER>XXXXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</USER>
 </AUTH>
 <QUERY CMD="AV_WORK_SEARCH">
  <TEXT TYPE="TITLE">the big lebowski</TEXT>
 </QUERY>
</QUERIES>

 

Response:

<RESPONSES>
 <RESPONSE STATUS="OK">
   <RANGE>
      <START>1</START>
      <END>2</END>
      <COUNT>2</COUNT>
   </RANGE>
   <AV_WORK ORD="1">
      <GN_ID>240141904-0CB5A87DFCF93686F50A566512A4CD66</GN_ID>
      <TITLE>The Big Lebowski</TITLE>
      <DATE TYPE="ORIGINALRELEASE">1998-03-06</DATE>
      <DURATION UNITS="SEC">7005</DURATION>
      <RATING>
         <SYSTEM>MPAA (USA)</SYSTEM>
         <CODE>R</CODE>
         <REASON>Pervasive Strong Language, Drug Content, Brief Violence, Sexuality</REASON>
      </RATING>
      <PRODUCTION_TYPE ID="16635">Motion Picture</PRODUCTION_TYPE>
      <GENRE ID="33756">Comedy</GENRE>
      <GENRE ID="33761">Mystery &amp; Suspense</GENRE>
      <SYNOPSIS>Jeff Bridges plays Jeff Lebowski who insists on being called &quot;the Dude,&quot; a laid-back, easygoing burnout who happens to have the same name as a millionaire whose wife owes a lot of dangerous people a whole bunch of money -- resulting in the Dude having his rug soiled, sending him spiraling into the Los Angeles underworld.</SYNOPSIS>
      <CONTRIBUTOR RANK="1">
         <NAME>Jeff Bridges</NAME>
         <GN_ID>238220984-8935A3E8ECD6D9E286909331740F18FD</GN_ID>
         <CONTRIBUTION>
            <CONTRIBUTION_TYPE MEDIASPACE="VIDEO" ID="15942">Actor</CONTRIBUTION_TYPE>
            <CHARACTER>The Dude</CHARACTER>
         </CONTRIBUTION>
      </CONTRIBUTOR>
      <CONTRIBUTOR RANK="2">
         <NAME>John Goodman</NAME>
         <GN_ID>238893028-E628BAC13E0DD6DE5A59A1D49574BC2A</GN_ID>
         <CONTRIBUTION>
            <CONTRIBUTION_TYPE MEDIASPACE="VIDEO" ID="15942">Actor</CONTRIBUTION_TYPE>
            <CHARACTER>Walter Sobchak</CHARACTER>
         </CONTRIBUTION>
      </CONTRIBUTOR>
      <CONTRIBUTOR RANK="3">
         <NAME>Julianne Moore</NAME>
         <GN_ID>238433860-41835028B0C3CDDA4CA08B4F8C69CA44</GN_ID>
         <CONTRIBUTION>
            <CONTRIBUTION_TYPE MEDIASPACE="VIDEO" ID="15942">Actor</CONTRIBUTION_TYPE>
            <CHARACTER>Maude Lebowski</CHARACTER>
         </CONTRIBUTION>
      </CONTRIBUTOR>
   </AV_WORK>
 </RESPONSE>
</RESPONSES>

Language Settings

To change the language of all API responses (for available languages), use the <LANG> element with any API call with a 3 letter ISO 639-2 language code (e.g. 'eng' for English, and 'jpn' for Japanese). For example, to search for "The Big Lebowski" in German:

<QUERIES>
 <LANG>ger</LANG>
 <AUTH>
  <CLIENT>XXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</CLIENT>
  <USER>XXXXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</USER>
 </AUTH>
 <QUERY CMD="AV_WORK_SEARCH">
  <TEXT TYPE="TITLE">the big lebowski</TEXT>
 </QUERY>
</QUERIES>