Boxfish Node API

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

Install

Install via npm.

$ npm install boxfish

Features

• Interactive REPL
• Auto generated documentation (npm run doc)
• Large test coverage
• Works in the browser

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 Boxfish.doc(). To run an example API call
on a method, do Boxfish.<method>.example() and it will run an
example if possible.

Helpers:
  Boxfish.doc(); // Show a list of methods and their parameters
  Boxfish.authorize.help(); // Show a methods parameters and description
  Boxfish.channels.getServices.example(); // Run the method with example parameters
undefined
>

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 ) ✔
    Boxfish.channels.getThumbnails( :channels, :channelType, :time, :size ) ✔
    Boxfish.channels.getDiscussions( :channels, :channelType, :lineupId, :time ) ✔

• 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 ) ✔
    Boxfish.topics.getChannelEntities( :channels, :channelType, :startTime, :endTime ) ✔
    Boxfish.topics.getChannelEntitiesLatest( :channels, :channelType, :date ) ✔
    Boxfish.topics.getRelated( :topic ) ✔

• 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 - These 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 ) ✔

• alerts - The alerts endpoint provides notification mechanisms for monitored events, such as program/show reminders or topics of interest being discussed.

    Boxfish.alerts.add(:keywords, :lineupId, :callbackURL, :uuid)
    Boxfish.alerts.list(:uuid)
    Boxfish.alerts.remove(:uuid, :keywords)

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"));
});

Browser

The library is compatible with Browserify. To use standalone Boxfish in the browser, run npm build and include build/boxfish.min.js. To run browser tests, open test/browser/runner.html.

Documentation

Boxfish.authorize( :id, :secret )

• id Your client ID.
• secret Your client secret

Authorizes with Boxfish API with your credentials.

Boxfish.channels.getServices( :zipcode )

/channels/services/:zipcode

• zipcode The 5 digit US ZIP code to get the local television providers.

Gets the available television service providers for the provided ZIP code region.

Boxfish.channels.createLineup( :serviceId )

/channels/lineup/:serviceId/create

• serviceId The service id to generate the lineup for.

Generates a channel lineup id for the provided service, accessible using the channel lineup id.

Boxfish.channels.getLineup( :lineupId [, :hd] )

/channels/lineup/:lineupId

• lineupId The line up ID.
• hd Whether to return HD channels or false to return non-HD channels only.

Gets the channels for a provided lineup id.

Boxfish.channels.getThumbnails( :channels [, :channelType] [, :time] [, :size] )

/image/url/:channels/:channelType/:time/:size

• channels A list of channels.
• channelType The type of channels i.e. Boxfish, rovio etc.
• time A time of the query.
• size Configure the size of the image.

Get live thumbnails for channels.

Boxfish.channels.getDiscussions( :channels [, :channelType], :lineupId [, :time] )

/discussions/:channels/:channelType/:lineupId/:time

• channels A list of channels.
• channelType The type of channels i.e. Boxfish, rovio etc.
• lineupId The line up ID.
• time A time of the query.

Gets the discussions on a channel(s).

Boxfish.trending.getTopics( :category [, :limit] )

/trending/topics/:category

• category Boxfish category.
• limit Limit the results returned.

Gets the available television service providers for the provided ZIP code region.

Boxfish.trending.getDiscussions( :category, :lineupId [, :airing] )

/trending/discussions/:category/:lineupId

• category Boxfish category.
• lineupId The line up ID.
• airing Whether to return programming that has completed.

Gets trending discussions: the latest conversations discussing currently trending topics on live TV. Provides a realtime "What's Hot" view of TV. Trending is based on what TV is speaking about, rather than Twitter or Viewer beheviour.

Boxfish.search.all( :query, :lineupId, :category [, :limit] [, :types] )

/search/all/:query/:lineupId/:category

• query The search term.
• lineupId The line up ID.
• category Boxfish category.
• limit Limit the results returned.
• types The 'types' parameter is used to include/exclude certain search types in the output. Supported values are: 'channels', 'programs', 'mentions', 'all'.

Search for channels, programs or mentions.

Boxfish.search.mentions( :query, :lineupId, :category [, :limit] )

/search/mentions/:query/:lineupId/:category

• query The search term.
• lineupId The line up ID.
• category Boxfish category.
• limit Limit the results returned.

Search for keywords or phrase mentions, globally or by category (e.g. "news", "sports" or "lifestyle"), based on what is being discussed on live TV. Results are filtered so that only one (the latest) result is returned for any individual program. Search only supports single keyword queries.

Boxfish.search.programs( :query, :lineupId [, :limit] )

/search/programs/:query/:lineupId

• query The search term.
• lineupId The line up ID.
• limit Limit the results returned.

Search for programs.

Boxfish.search.channels( :query, :lineupId [, :limit] )

/search/channels/:query/:lineupId

• query The search term.
• lineupId The line up ID.
• limit Limit the results returned.

Search for Channels.

Boxfish.metrics.getMentions( :keywords [, :start] [, :stop] [, :granularity] )

/metrics/mentions/:keywords/:start/:stop

• keywords The token(s) to search for; N-gram/multi-word exact expressions are allowed, but not fuzzy search.
• start The start time of the query.
• stop A end time of the query.
• granularity The granularity of the response data; this can be any of the tokens: minute, hour, day, month, year

Gets granular mention counts and times of a keyword.

Boxfish.metrics.getChannels( :keywords, :channels [, :channelType] [, :start] [, :stop] )

/metrics/channel/:keywords/:channels/:channelType/:start/:stop

• keywords The token(s) to search for; N-gram/multi-word exact expressions are allowed, but not fuzzy search.
• channels A list of channels.
• channelType The type of channels i.e. Boxfish, rovio etc.
• start The start time of the query.
• stop A end time of the query.

Gets minute by minute mention counts for a keywords on specific channel(s).

Boxfish.metrics.getCount( :keywords, :channels [, :channelType] [, :start] [, :stop] )

/metrics/count/:keywords/:channels/:channelType/:start/:stop

• keywords The token(s) to search for; N-gram/multi-word exact expressions are allowed, but not fuzzy search.
• channels A list of channels.
• channelType The type of channels i.e. Boxfish, rovio etc.
• start The start time of the query.
• stop A end time of the query.

Get total mention count metrics for keywords on specific channel(s).

Boxfish.metrics.getGraph( :keywords, :channels [, :channelType] [, :start] [, :stop] )

/metrics/graph/:keywords/:channels/:channelType/:start/:stop

• keywords The token(s) to search for; N-gram/multi-word exact expressions are allowed, but not fuzzy search.
• channels A list of channels.
• channelType The type of channels i.e. Boxfish, rovio etc.
• start The start time of the query.
• stop A end time of the query.

Get metrics array with a datapoints parameter to generate a graph.

Boxfish.epg.getSchedule( :channels [, :channelType], :lineupId [, :start] [, :stop], :category [, :upcoming] )

/epg/channels/:channels/:channelType/:lineupId/:start/:stop/:category

• channels A list of channels.
• channelType The type of channels i.e. Boxfish, rovio etc.
• lineupId The line up ID.
• start The start time of the query.
• stop A end time of the query.
• category Boxfish category.
• upcoming If true, only shows with a start time after the current or 'time' parameter value (as opposed to those which are in progress). Can be used, e.g. for "Upcoming" shows on a channel.

Gets the EPG/program schedule for provided channel(s)

Boxfish.epg.getGuide( :lineupId [, :start] [, :stop], :category [, :upcoming] )

/epg/guide/:lineupId/:start/:stop/:category

• lineupId The line up ID.
• start The start time of the query.
• stop A end time of the query.
• category Boxfish category.
• upcoming If true, only shows with a start time after the current or 'time' parameter value (as opposed to those which are in progress). Can be used, e.g. for "Upcoming" shows on a channel.

Gets the EPG/program schedule for the provided lineup

Boxfish.topics.getChannelTagsLatest( :channels [, :channelType] [, :time] [, :limit] )

/tags/nested/latest/:channels/:channelType/:time

• channels A list of channels.
• channelType The type of channels i.e. Boxfish, rovio etc.
• time A time of the query.
• limit Limit the results returned.

Gets tags for a specified channel(s).

Boxfish.topics.getChannelTags( :channels [, :channelType] [, :start] [, :stop] [, :limit] )

/tags/nested/channel/:channels/:channelType/:start/:stop

• channels A list of channels.
• channelType The type of channels i.e. Boxfish, rovio etc.
• start The start time of the query.
• stop A end time of the query.
• limit Limit the results returned.

Gets tags for a specified channel(s) with a start and stop.

Boxfish.topics.getProgramTags( :channels [, :channelType] [, :time] [, :limit] )

/tags/nested/programs/:channels/:channelType/:time

• channels A list of channels.
• channelType The type of channels i.e. Boxfish, rovio etc.
• time A time of the query.
• limit Limit the results returned.

Gets tags for a specified program and channel(s)

Boxfish.topics.getChannelEntitiesLatest( :channels [, :channelType] [, :time] [, :limit] )

/entities/latest/:channels/:channelType/:time

• channels A list of channels.
• channelType The type of channels i.e. Boxfish, rovio etc.
• time A time of the query.
• limit Limit the results returned.

Gets the most recent entities for a specified channel. Entities are nested one level deep.

Boxfish.topics.getChannelEntities( :channels [, :channelType] [, :start] [, :stop] [, :limit] )

/entities/channel/:channels/:channelType/:start/:stop

• channels A list of channels.
• channelType The type of channels i.e. Boxfish, rovio etc.
• start The start time of the query.
• stop A end time of the query.
• limit Limit the results returned.

Gets entities for a specified channel for a specified length. Entities are nested one level deep.

Events

The Boxfish object is an instance of EventEmitter and emits the following events.

error:request

When an error in a request is encountered.

error:request:<status code>

When an error is encountered in a request, scoped by status code. e.g. error:request:500 is an internal Boxfish server error.

error:request:[client|redirection|server]

When a client, redirection or server error is encountered in a request.

TODO

• Related endpoints.
• Alerts endpoint.
• Fix optional parameters occuring before required ones.