#Gracenote eyeQ

Gracenote eyeQ for Node delivers a rich set of video metadata to help power realtime interactive experiences. It allows TV provider, channel, and program lookups, as well as text-based lookups of movies and television series.

~Gracenote Developer Documentation

##Introduction

Gracenote eyeQ is "an Interactive Program Guide (IPG) featuring local, national and international TV listings, as well rich program-related photos and imagery. With up to 21 days programming data for 28 countries, Gracenote eyeQ arms TV manufacturers and cable-operators with a means to break free from old fashioned TV grids to produce dynamic interfaces."

This module was developed for the 2014 TVOT Hackathon. It is an API wrapper for the Gracenote eyeQ API, designed to streamline the development of real-time IPTV applications. The eyeQ API is based in XML, this module provides a JSON shim, so you can format queries in javascript and receive JSON responses from the server.

For more information on TVOT visit www.tvot.tv.

For more information on Gracenote eyeQ visit the documentation.

##Methods

###Register

Before an application can make requests to the Gracenote eyeQ API it needs to an Account ID and a User ID. The Account ID is provided on the Gracenote Developer Portal. You can create an account ID here. The User ID is generated during this method. Developers DO NOT need to provide a User ID, it is retrieved automagically. Both your application User ID and Account ID will be cached, so that you do not have to provide these details on subsequent method calls.

Once the callback method fires you can freely make method calls or bind method calls to events.

// Bring in the eyeQ module from NPM
var eyeq = require("eyeq");

// Pass in an Account ID, which you can generate 
// from the Gracenote Developer Portal
eyeq.register("XXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", function(response) {
    // Response contains User ID in JSON
    
    // Do other eyeq API queries...
}); 

###Provider Lookup

The provider lookup method is probably the most common entry point into the Gracenote eyeQ API. This method accepts two parameters, the first being a zip code, and the second being a callback that exposes the response object in the first parameter of the callback. The response object will contain a list of the available Television Service Providers in that area. This also includes the GN_ID, which can be used to lookup channel listings and other details.

//Provide any valid ZipCode as int/ var
eyeq.providerLookup(90210, responeHandler);

// Callback
function responseHandler(response) {
    console.log(response)
}

###Channel Lookup

The channel lookup method accepts a GN_ID, and returns a JSON formatted list of Channels for any given provider ID.

// Get provider Id from Provider Lookup
var GN_ID = "320380286-B44501791AC650A36A897A9B88209556";

eyeq.channelLookup(GN_ID, responseHandler);

// Callback
function responseHandler(response) {
    //Handle response    
}

###Grid Lookup

Grid Lookup returns list of programs for a given television channel and a given timeframe. This method takes two parameters, the first being a config object with the channel GN_ID, and the ISO-8601 formatted start and end dates.

// Get Channel Id from Channel Lookup
var config = {
    id    : "251545958-935BCC7F5502DCD265D67EBF29B2EB2B",
    start : "2014-05-29T18:00",
    end   : "2014-05-29T19:00"
};

//
eyeq.gridLookup(config, responseHandler);

// Callback
function responseHandler(response) {
    // Handle response...
}

###Search

Search the Gracenote database for videos, movies, and television shows by title.

// Case Insensative title search 
eyeq.search("the big lobowski", responseHandler);

// Callback
function responseHandler(response) {
    // Handle response...
}

##Todo

• Add Language Support

• Add Region Support

• Refactor HTTP request and error handling

• Refactor JSON output to lowercase parameter names

• Tests