Boxfish Node API

This is the Node.js interface for the Boxfish API.

Install

Install via npm.

$ npm install boxfish

Features

• Interactive REPL
• Auto generated documentation (npm run doc)

Usage

Require the API in your program.

var Boxfish = require("boxfish");

Boxfish.authorize("cake", "candle").then(function() {
	return Boxfish.channels.getServices();
}).then(function(services) {
	console.log("Services!")
}).catch(function(err) {
	console.log("Oh no, error!");
});

One of the main features of the Boxfish API is ease of use so try using the API in the REPL. It adds several helper functions to make testing a real treat.

$ node
> var Boxfish = require("boxfish");
Welcome to the Boxfish API.

Each API function has it's own .help() function. For a list
of functions, use .list(). Have fun playing around. Don't
forget to .authorize() first with your credentials.

Examples:
  Boxfish.channels.help(); // List of channel functions
  Boxfish.channels.getServices.help() // Parameters required

> Boxfish.authorize("cake", "candle");

Methods

The API has the following namespaces:

• channels - Channels provides channel lists for provided ZIP codes, services and related content. See channels.

    Boxfish.channels.getServices( :zipcode ) ✔
    Boxfish.channels.createLineup( :service ) ✔
    Boxfish.channels.getLineup( :lineupId ) ✔
    Boxfish.channels.getRelatedContent( :channels, :channelType, :time ) [REVIEW]
    Boxfish.channels.getThumbnails( :channels, :channelType, :time, :size ) ✔ [REVIEW]
    Boxfish.channels.getDiscussions( :channels, :channelType, :lineupId, :time ) ✔ [REVIEW]

• trending - The trending discussions endpoint provides search results for currently trending topics.

    Boxfish.trending.getTopics( :category ) ✔
    Boxfish.trending.getDicussions( :category, :lineupId ) ✔

• topics - Get tags or entities for programs.

    Boxfish.topics.getChannelTags( :channels, :channelType, :startTime, :endTime ) ✔
    Boxfish.topics.getChannelTagsLatest( :channels, :channelType, :date ) ✔ [REVIEW]
    Boxfish.topics.getChannelEntities( :channels, :channelType, :startTime, :endTime ) ✔
    Boxfish.topics.getChannelEntitiesLatest( :channels, :channelType, :date ) ✔ [REVIEW]
    Boxfish.topics.getRelated( :topic ) [REVIEW]

• search - Search tags, programs, channels or all.

    Boxfish.search.all( :query, :lineupId, :categories, :limit, :types ) ✔
    Boxfish.search.mentions( :query, :lineupId, :categories ) ✔
    Boxfish.search.programs( :query, :lineupId ) ✔
    Boxfish.search.channels( :query, :lineupId ) ✔

• metrics - Metrics provides real time updated statistics for entity keywords or expressions, minute by minute, or aggregated by year, month, day or hour.

    Boxfish.metrics.getMentions( :keywords, :start, :stop ) ✔
    Boxfish.metrics.getChannels( :keywords, :channels, :channelType, :start, :stop ) ✔
    Boxfish.metrics.getCount( :keywords, :channels, :channelType, :start, :stop ) ✔
    Boxfish.metrics.getGraph( :keywords, :channels, :channelType, :start, :stop ) ✔

• epg - Thse epg endpoint provides access to program (TV show) EPG data.

    Boxfish.epg.getSchedule( :channels, :channelType, :lineupId, :start, :stop, :category ) ✔
    Boxfish.epg.getGuide( :lineupId, :start, :stop, :category ) ✔

Every API methods can be called in the following ways:

1. Using a callback.

Boxfish.channels.getServices(89083, function(err, data) {
	if(err) console.log("Oh noes! Error!");
	else console.log("Got dem services", data);
});

2. Using promises.

Boxfish.channels.getServices(89083).then(function(data) {
	console.log("Got dem services", data);
}).catch(function(err) {
	console.log("Oh noes! Error!");
});

3. Implicit arguments. So if we had an API function that required the following data; startTime, endTime, count, we can implicitly pass those arguments in that order to the function. (Promises are supported here if callback is omitted!)

Boxfish.search.programs("obama", "231jk4hkj-the-cake-is-a-lie-123jdk", function(err, data) {
	if(err) console.log("Oh noes! Error!");
	else console.log("Your programs: ", data);
});

4. Explicit arguments. Instead of passing the arguments as a list, you can pass them in an object so order does not matter.

Boxfish.search.programs({
	lineupId: "231jk4hkj-the-cake-is-a-lie-123jdk",
	query: "obama"
}, function(err, data) {
	if(err) console.log("Oh noes! Error!");
	else console.log("Your programs: ", data);
});

5. Using a callback, but getting request stream. WARNING: This method does not handle any errors in the request. That's up to you.

Boxfish.search.programs("obama", "231jk4hkj-the-cake-is-a-lie-123jdk", function(request) {
	request.pipe(fs.createWriteStream("./my-programs.json"));
});

Channels

Channels provide channel lists for provided ZIP codes and service providers.

TODO

• Emit errors on the API object.
• Automate testing. The Endpoint tests work but are silly.
• Have <fn>.example() run an example request using example data.