Kannuu Discovery APIs

Kannuu provides APIs for the delivery of our core content discovery services to remote clients over the WWW or other network-based infrastructures.

For a high level overview of our text entry interfaces please see http://www.kannuu.com/product/user-interface/.

For a high level overview of our recommendation and personalization services please see http://www.kannuu.com/product/recommendation/.

These API services include:

  • Lookup Configuration, pre-requisite API for the Lookup API service.
  • Lookup, for our predictive and auto-suggest Search service.
  • Suggest, for content item recommendations service.
  • Locker, for end-user data hosting to enable the perosnalization of discovery services.
  • Metadata Input, for importing searchable metadata terms into the system.

APIs consist of callable methods and API endpoints. To use an API you must send a “GET” request payload over HTTP to the correct API endpoint and will receive a formatted response. These calls and endpoints are outlined in the documentation at this URL.

Below is a visual overview of where these APIs apply in a demonstration app. You can review the Kannuu offering by running the live demonstration located at: http://lettergrid.kannuu.com. USE YOUR KEYBOARD ONLY [arrow keys, A, B, C, D and backspace/escape keys only]



Please direct any questions or comments to support@kannuu.com.

Lookup Configuration API

This section outlines the lookup configuration API which is required prior to accessing the lookup APIs.

GET {host}/cfg/2/api_key/{key}/{token}/{loc}?adult={adult}

The host value to use is api.kannuu.com unless otherwise instructed by your Kannuu representative

Returns an object with configuration information for using the Lookup API. In particular the returned auth_key value is a mandatory parameter for the lookup API call.

  • Parameters
  • key
    (required)string A customer assigned API key value. Contact your Kannuu representative to be assigned an API key.
    token
    (required)string A unique device token ID for the device. May be the MAC address or other uniquely defined UUID. The same token ID should always be used for an individual client instance.
    adult
    (optional)boolean A boolean that determines whether adult titles will appear in the results.
  • Response 200SHOW
  • Content-Type: application/json
    stat
    string Response status. "ok" or "fail"
    response
    object Object containing configuration information for lookup calls.
    auth_key
    string String identifying the authorization key to be used for the lookup API calls. This key value expires after 20 minutes of inactivity after which the configuration API must be called again to refresh it.
    loc
    string String indicating deployed to environment. "dev", "prod", etc.
    imagehost
    array Array containing strings with base URLs for imagehost(s).
    image.sgrp
    string String that is passed to the Kannuu image delivery service to provide as a key to describe the image manipulation behavior.
    image.key
    number Number that is passed to the Kannuu image delivery service that acts as an asset versioning key. When the key changes, it acts as a cache buster providing fresh images region wide.
    host
    array Array containing strings with base URLs for the Lookup API.
    src
    array Array of strings describing available searchable datasources. E.g. "home", "all", "title", "person", etc.
    	{
    		"stat": "ok",
    		"response": {
    			"auth_key": "sample-auth-key-1decb94138d9",
    			"loc": "sample",
    			"imagehost": [
    				"image.example.com"
    			],
    			"src": [
    				"title",
    				"person"
    				"keyword",
    				"channel",
    				"home",
    				"all"
    			],
    			"image": {
    				"sgrp": "group",
    				"key": "1"
    			},
    			"host": [
    				"example.com"
    			]
    		}
    	}
    												

Lookup API

This section describes the Lookup API call.

GET {host}/lookup?auth_key={}&src={}

The host, auth_key, and src values to use are included in the lookup configuration API response.

Returns an object with menu options and result selections.

  • Parameters
  • auth_key
    (required)string Authorization key as returned by the configuration API call.
    src
    (required)string A named data source identifying the Kannuu index. Possible values for this parameter are returned in "src" array field of the config API response.
    pref
    (optional)string Comma separated string values. Can contain [abbrev, allsel, adult]. Abbrev returns abbreviated summary records. Allsel returns selections for all menu IDs(including menu 1). Adult uses adult oriented indexes if available.
    id
    (optional)number The ID of the menu item that should be used as the starting point for the menu lookup. When beginning a new lookup or resetting an index search then this menuId value should always be set to 1.
    opts
    (optional)number The number of choices to return per “options” array. Typically 4 is used to correspond with a 4 direction input type. Default: 4
    count
    (optional)number The maximum number of menu items to return in the result. A value between 20 and 100 is recommended. Default: 1
    levels
    (optional)number The number of levels of the menu tree from the current search node that should be prefetched. This can be a number between 0 and 4. 0 or not present indicates that as many levels as necessary to represent the desired menuCount will be processed. A value of 2 is recommended in order to better optimize the search and results being returned by prefetching 2 navigational levels. Default: 0
    q
    (optional)string Used to specify a search term instead of a specific menuId. (e.g. q=star%20wars) Note - menuId must be set to “1” when specifying "q" parameter values. No default.
    sel
    (optional)number Used to specify how many weighted selections are to be returned for the requested menuId. Note that no selections are returned for a menuId of 1 ("root" menu) unless the "allsel" preference value is also used. Default: 0
    sel_start
    (optional)number Used for paging selection results in conjunction with the SEL paramater value. Default: 0
    sel_max
    (optional)number Maximum number of selections that will ever need to be retrieved. A value between 0 and 100 inclusive may be used. Using this paramter helps to optimize server selection retrieval processing. Default: 0
    jsonp
    (optional)string Identifies a callback function for the response. No default.
  • Response 200SHOW
  • Content-Type: application/json
    stat
    string Response status. "ok" or "fail"
    api
    string Specifies the api version. This value match the version requested.
    fts
    number Index creation timestamp. Can be used to check for periodic index changes.
    root
    string Identifies the menuId to start at in the response body.
    response
    object Response body contianing a map of Menu Objects.
    key
    string String containing characters in current search progression.
    options
    array Array of menu option objects.
    more
    string String indicating menuId for additional menu choices.
    sel
    array An Array of <selection> Detail Objects, where <selection> can be of type Movie, TV Show, Person, or Keyword.
    	{
    		"api": "2",
    		"stat": "ok",
    		"fts": 1363023079,
    		"root": "4634",
    		"response":
    			{
    				"4634":
    					{
    						"key": [],
    						"options":
    							[
    								{"v": "o", "i": 12646262},
    								{"v": "u", i": 13419046},
    								{"v": "X 1138", "l": {<SELECTION DETAIL OBJECT>}},
    								{"v": "y", "i": 13568744}
    							],
    						"more": 4766
    					},
    				"4766":
    					{
    						"key": [],
    						"options":
    							[
    								{"v": "é","i": 13574607}
    							]
    					},
    				"12646262":
    					{
    						"key": ["o"],
    						"options":
    							[
    								{"v": "u", "i": 12646635},
    								{"v": "r", "i": 12699022},
    								{"v": "m", "i": 12822110},
    								{"v": "ng", "i": 13401141}
    							],
    						"more": 12646374
    					},
    				"13419046":
    					{
    						"key": ["u"],
    						"options":
    							[
    								{"v": "n", "i": 13419266},
    								{"v": "mb", "i": 13503610},
    								{"v": "r", "i": 13527422},
    								{"v": "lin... Ingrid", "l": {<SELECTION DETAIL OBJECT>}}
    							],
    						"more": 13419210
    					},
    				"13568744":
    					{
    						"key": ["y"],
    						"options":
    							[
    								{"v": "", "l": {<SELECTION DETAIL OBJECT>}}
    							]
    					}
    			}
    	}
    
    													
  • Selection Object Reference movieSHOW
  • Content-Type: application/json
    cast
    array Array containing objects representing cast memebers.
    category
    string String representing item type. Movie objects will contain "movie".
    cert
    string MPAA certification rating.
    director
    array Array containing objects representing the director(s).
    genres
    array Array containing strings representing applicable genres.
    id
    string Unique Kannuu id for this item.
    ids
    array Array containing strings representing ids for other services.
    image
    string String representing URL for item's poster.
    keywords
    array Array containing strings representing applicable keywords.
    knxt
    array Array containing an object describing the jump to another index.
    label
    string String representing a template for rendering the label for the title.
    lang
    string String representing the language of the item.
    network
    string String representing the network for the item.
    overview
    string String representing short description of the item.
    provider
    object Object containing EPG and/or VOD information.
    rating_expl
    array Array containing strings representing reasons for the item's certification.
    ratings
    object Object containing rating information(ex: Rotten Tomatoes).
    released
    string String representing release date. Format: yyyy-mm-dd
    runtime
    number Number representing runtime in minutes.
    synopsis
    string String representing plot description.
    title
    string Title of the item.
    trailer
    array Array of objects containiner trailer information.
    type
    number Numeric representation of item type. Movies are always 1.
    w
    number Number representing item's weighted value.
    year
    number Number representing item's 4-digit release year.
    ymal
    array Array containing objects representing other titles a user may also like.
    	{
    		image: "http://host/t/p/w185/uPxtxhB2Fy9ihVqtBtNGHmknJqV.jpg",
    		year: 2013,
    		id: "11765996",
    		category: "movie",
    		ratings: <Ratings Object>,
    		genres: [
    			"Space"
    		],
    		network: "Warner Bros.",
    		title: "Gravity",
    		cert: "PG-13",
    		label: "{title}",
    		ymal: [
    			<Movie Object>,
    			<Movie Object>,
    			<Movie Object>
    		],
    		provider: {
    			epg: [
    				<Episode Guide Entry Object>,
    				<Episode Guide Entry Object>,
    				<Episode Guide Entry Object>
    			],
    		}
    		type: 1,
    		director: [
    			<Person Object>,
    			<Person Object>,
    		],
    		released: "2013-10-04",
    		lang: "English",
    		rating_expl: [
    			"Adult Language",
    			"Adult Content"
    		],
    		ids: <IDS Object>,
    		cast: [
    			<Person Object>,
    			<Person Object>
    		],
    		synopsis: "A medical engineer and a veteran astronaut are on a space-walk during a Space Shuttle mission when debris from a foreign satellite crashes into them and destroys their shuttle, forcing them to work to-gether while they're stranded in space.",
    		w: 2673,
    		runtime: 91,
    		trailer: {
    			bid: 472,
    			type: "sp",
    			cid: "e129267"
    		}
    	}
    													
  • Selection Object Reference tv showSHOW
  • Content-Type: application/json
    cast
    array Array containing objects representing cast memebers.
    category
    string String representing item type. Movie objects will contain "movie".
    cert
    string MPAA certification rating.
    director
    array Array containing objects representing the director(s).
    genres
    array Array containing strings representing applicable genres.
    id
    string Unique Kannuu id for this item.
    ids
    array Array containing strings representing ids for other services.
    image
    string String representing URL for item's poster.
    knxt
    array Array containing an object describing the jump to another index.
    label
    string String representing a template for rendering the label for the title.
    lang
    string String representing the language of the item.
    network
    string String representing the network for the item.
    provider
    object Object containing EPG and/or VOD information.
    released
    string String representing release date. Format: yyyy-mm-dd
    runtime
    number Number representing runtime in minutes.
    season
    object Object containing per-season information.
    synopsis
    string String representing plot description.
    title
    string Title of the item.
    today
    boolean Boolean that is true if tv show airs today.
    type
    number Numeric representation of item type. TV shows are always 5.
    w
    number Number representing item's weighted value.
    ymal
    array Array containing objects representing other titles a user may also like.
    	{
    		image: “http://host/768218.jpg",
    		id: "10504250",
    		category: "series",
    		genres: [
    			"Comedy"
    		],
    		network: "Chuck Lorre Productions, Inc.",
    		title: "The Big Bang Theory",
    		synopsis: "A group of socially dysfunctional nerds living in a shel-tered academic environment meet their new neighbor, who happens to be a pretty blonde aspiring to be an actress, and their lives take a course that none of them ever expected.",
    		label: "{title}",
    		ymal: [
    			<Movie Summary Object>,
    			<Movie Summary Object>,
    			<Movie Summary Object>
    		],
    		provider: {
    			epg: [
    				<Episode Guide Entry Object>,
    				<Episode Guide Entry Object>,
    				<Episode Guide Entry Object>
    			],
    			vod: [
    				<VOD Object>,
    				<VOD Object>,
    				<VOD Object>
    			]
    		}
    		type: 5,
    		season: {
    			0: <Season Object>,
    			1: <Season Object>
    		},
    		director: [
    			<Person Object>
    		],
    		released: "2007-09-24",
    		lang: "English",
    		ids: <IDS Object>,
    		cast: [
    			<Person Object>,
    			<Person Object>,
    			<Person Object>
    		],
    		cert: "TV-PG",
    		w: 2515,
    		runtime: 30
    	}
    
    													
  • Selection Object Reference personSHOW
  • Content-Type: application/json
    bio
    string Personal information about the person.
    dob
    string Date of birth.
    dod
    string Date of death(if person is deceased).
    id
    string Kannuu identifier for the person.
    image
    string URL to image of the person.
    kf
    array Array containing movie or tv titles this person is "Known For".
    knxt
    array Array containing an object describing the jump to another index.
    name
    string Name of the person.
    pfm
    array Array containing person objects. "pfm" stands for "Person Friend Map", and refers to other people this person has worked with.
    roles
    array Array of strings indicating whether this person is an actor and/or director.
    type
    number Numeric representation of item type. People are always 2.
    w
    number Number representing person's weighted value.
    	{
    		bio: "Walter Bruce Willis, better known as Bruce Willis, is …",
    		name: "Bruce Willis",
    		roles: [
    			"Actor"
    		],
    		dob: "1955-03-19 00:00:00.0000000",
    		image: "http://host/t/p/w185/kI1OluWhLJk3pnR19VjOfABpnTY.jpg",
    		pfm:
    			[
    			<Person Object>,
    			<Person Object>,
    			<Person Object>
    			],
    		dod: "",
    		label: "{name}",
    		w: 709,
    		knxt:
    			[
    			<Kannuu Next Object>
    			],
    		type: 2,
    		id: "kn4340709941614810953",
    		kf:
    			[
    			<TV Show Object>,
    			<Movie Object>
    			]
    	}
    													

Suggest API

This section outlines the KanWAS suggestions API which provides recommendations for movie or TV show titles.

GET /suggest/{type}{?api_key}{?q}{?y}{?id}{?max}{?filter}

Returns an object with recommended content for the supplied title.

  • Parameters
  • api_key
    (required)string A customer assigned API key value. Contact your Kannuu representative to be assigned an API key.
    type
    (required)string A string that identifies the item type for which recommendations are being requested. Values ["movie", "tv"] may be used.
    q
    string A string representing the query (title) of the item for which recommendations are requested. One of "q" or "id" must be used.
    y
    number Used with "q", identifies a number representing the 4-digit year that the title was released or first aired.
    id
    string A string representing an item's id. Including the id parameter will also add the "id" to the results on items which have the same id type.
    max
    number Limits the maximum number of results. Default: 25
    filter
    string Can be used with a value of "maxcert:{cert}" where {cert} is G, PG, PG-13, or R to limit the maximum MPAA rating on results.
  • Response 200SHOW
  • Content-Type: application/json
    stat
    string Response status. "ok" or "fail"
    response
    object Object containing the response result.
    result
    array Array containing object with result details.
    title
    string String representing the requested item title.
    director
    array Array of objects representing the item's director(s).
    name
    string String representing the director's name.
    cert
    string String representing the item's certification rating.
    similar
    array Array of objects representing the recommended items for the listed title.
    title
    string String representing the recommended item's title.
    image
    string URL to a poster image resource for the recommended item.
    year
    number Number representing the recommended item's release year.
    cert
    string String representing the recommended item's certification rating.
    id
    string String representing the recommended item's id value.
    	{u'stat': u'ok',
    	 u'response': {u'result': [{u'cert': u'PG-13',
    								u'title': u'Oblivion',
    								u'year': 2013,
    								u'director': [{u'name': u'Joseph Kosinski'}],
    								u'id': u'21665209',
    								u'image': u'http://ia.media-imdb.com/images/M/MV5BMTQwMDY0MTA4MF5BMl5BanBnXkFtZTcwNzI3MDgxOQ@@._V1_SX286_.jpg',
    								u'similar': [{u'cert': u'PG-13',
    											  u'id': u'11673468',
    											  u'image': u'http://ia.media-imdb.com/images/M/MV5BMTk2NzczOTgxNF5BMl5BanBnXkFtZTcwODQ5ODczOQ@@._V1_SX286_.jpg',
    											  u'title': u'Star Trek Into Darkness',
    											  u'year': 2013},
    											 {u'cert': u'R',
    											  u'id': u'11531900',
    											  u'image': u'http://ia.media-imdb.com/images/M/MV5BMTY3NTY0MjEwNV5BMl5BanBnXkFtZTcwNTE3NDA1OA@@._V1_SX286_.jpg',
    											  u'title': u'Looper',
    											  u'year': 2012},
    											 {u'cert': u'PG-13',
    											  u'id': u'11875174',
    											  u'image': u'http://ia.media-imdb.com/images/M/MV5BMTc5OTk4MTM3M15BMl5BanBnXkFtZTgwODcxNjg3MDE@._V1_SX286_.jpg',
    											  u'title': u'Edge of Tomorrow',
    											  u'year': 2014},
    											 {u'cert': u'PG-13',
    											  u'id': u'21704932',
    											  u'image': u'http://ia.media-imdb.com/images/M/MV5BMTY3MTI5NjQ4Nl5BMl5BanBnXkFtZTcwOTU1OTU0OQ@@._V1_SX286_.jpg',
    											  u'title': u'Pacific Rim',
    											  u'year': 2013},
    											 {u'cert': u'PG-13',
    											  u'id': u'11874970',
    											  u'image': u'http://ia.media-imdb.com/images/M/MV5BMTgwODk3NDc1N15BMl5BanBnXkFtZTgwNTc1NjQwMjE@._V1_SX286_.jpg',
    											  u'title': u'Dawn of the Planet of the Apes',
    											  u'year': 2014},
    											 {u'cert': u'R',
    											  u'id': u'21701249',
    											  u'image': u'http://ia.media-imdb.com/images/M/MV5BNDc2NjU0MTcwNV5BMl5BanBnXkFtZTcwMjg4MDg2OQ@@._V1_SX286_.jpg',
    											  u'title': u'Elysium',
    											  u'year': 2013},
    											 {u'cert': u'PG-13',
    											  u'id': u'10312880',
    											  u'image': u'http://ia.media-imdb.com/images/M/MV5BNDUyODAzNDI1Nl5BMl5BanBnXkFtZTcwMDA2NDAzMw@@._V1_SX286_.jpg',
    											  u'title': u'War of the Worlds',
    											  u'year': 2005},
    											 {u'cert': u'PG',
    											  u'id': u'tronlegacy',
    											  u'image': u'http://ia.media-imdb.com/images/M/MV5BMTk4NTk4MTk1OF5BMl5BanBnXkFtZTcwNTE2MDIwNA@@._V1_SX286_.jpg',
    											  u'title': u'Tron: Legacy',
    											  u'year': 2010},
    											 {u'cert': u'PG-13',
    											  u'id': u'11630095',
    											  u'image': u'http://ia.media-imdb.com/images/M/MV5BMjAzMzI5OTgzMl5BMl5BanBnXkFtZTgwMTU5MTAwMDE@._V1_SX286_.jpg',
    											  u'title': u"Ender's Game",
    											  u'year': 2013},
    											 {u'cert': u'PG-13',
    											  u'id': u'11923714',
    											  u'image': u'http://ia.media-imdb.com/images/M/MV5BMjIxNTU4MzY4MF5BMl5BanBnXkFtZTgwMzM4ODI3MjE@._V1_SX286_.jpg',
    											  u'title': u'Interstellar',
    											  u'year': 2014},
    											 {u'cert': u'PG-13',
    											  u'id': u'10030771',
    											  u'image': u'http://ia.media-imdb.com/images/M/MV5BMTMwODY3NzQzNF5BMl5BanBnXkFtZTcwNzUxNjc0MQ@@._V1_SX286_.jpg',
    											  u'title': u'Independence Day',
    											  u'year': 1996},
    											 {u'cert': u'PG-13',
    											  u'id': u'10860284',
    											  u'image': u'http://ia.media-imdb.com/images/M/MV5BMjE5NDQ5OTE4Ml5BMl5BanBnXkFtZTcwOTE3NDIzMw@@._V1_SX286_.jpg',
    											  u'title': u'Star Trek',
    											  u'year': 2009},
    											 {u'cert': u'PG-13',
    											  u'id': u'11580656',
    											  u'image': u'http://ia.media-imdb.com/images/M/MV5BMTM1NjUxMDI3OV5BMl5BanBnXkFtZTcwNjg1ODM3OA@@._V1_SX286_.jpg',
    											  u'title': u'Jack Reacher',
    											  u'year': 2012},
    											 {u'cert': u'PG-13',
    											  u'id': u'11672197',
    											  u'image': u'http://ia.media-imdb.com/images/M/MV5BMjIzMzAzMjQyM15BMl5BanBnXkFtZTcwNzM2NjcyOQ@@._V1._SY317_.jpg',
    											  u'title': u'Iron Man 3',
    											  u'year': 2013},
    											 {u'cert': u'PG-13',
    											  u'id': u'20989988',
    											  u'image': u'http://ia.media-imdb.com/images/M/MV5BMTYwOTEwNjAzMl5BMl5BanBnXkFtZTcwODc5MTUwMw@@._V1_SX286_.jpg',
    											  u'title': u'Avatar',
    											  u'year': 2009},
    											 {u'cert': u'PG-13',
    											  u'id': u'10291902',
    											  u'image': u'http://ia.media-imdb.com/images/M/MV5BMTQwNzI5NTQ0OF5BMl5BanBnXkFtZTYwMTI3Mjk2._V1_SX286_.jpg',
    											  u'title': u'I, Robot',
    											  u'year': 2004},
    											 {u'cert': u'R',
    											  u'id': u'darkcity',
    											  u'image': u'http://ia.media-imdb.com/images/M/MV5BMTg3MjI3NjYxM15BMl5BanBnXkFtZTcwODIyMzA4MQ@@._V1_SX286_.jpg',
    											  u'title': u"Dark City (Director's Cut)",
    											  u'year': 1998},
    											 {u'cert': u'R',
    											  u'id': u'30012944',
    											  u'image': u'http://ia.media-imdb.com/images/M/MV5BMTA4MDQxNTk2NDheQTJeQWpwZ15BbWU3MDE2NjIyODk@._V1_SX286_.jpg',
    											  u'title': u'Blade Runner (The Final Cut)',
    											  u'year': 1982},
    											 {u'cert': u'PG-13',
    											  u'id': u'11681802',
    											  u'image': u'http://ia.media-imdb.com/images/M/MV5BMTY3MzQyMjkwMl5BMl5BanBnXkFtZTcwMDk2OTE0OQ@@._V1_SX286_.jpg',
    											  u'title': u'After Earth',
    											  u'year': 2013},
    											 {u'cert': u'PG-13',
    											  u'id': u'31312135',
    											  u'image': u'http://ia.media-imdb.com/images/M/MV5BMTM1MzkyNzQ3OV5BMl5BanBnXkFtZTcwMDk1NTg2NQ@@._V1_SX286_.jpg',
    											  u'title': u'Cowboys & Aliens',
    											  u'year': 2011},
    											 {u'cert': u'PG-13',
    											  u'id': u'11241558',
    											  u'image': u'http://ia.media-imdb.com/images/M/MV5BMjA2MjQ2MzMwMV5BMl5BanBnXkFtZTcwMjIwODgzNA@@._V1_SX286_.jpg',
    											  u'title': u'Battle: Los Angeles',
    											  u'year': 2011},
    											 {u'cert': u'PG-13',
    											  u'id': u'11469151',
    											  u'image': u'http://ia.media-imdb.com/images/M/MV5BMTk2NTI1MTU4N15BMl5BanBnXkFtZTcwODg0OTY0Nw@@._V1_SX286_.jpg',
    											  u'title': u'The Avengers',
    											  u'year': 2012},
    											 {u'cert': u'PG-13',
    											  u'id': u'11469144',
    											  u'image': u'http://ia.media-imdb.com/images/M/MV5BMjI5NTM5MDA2N15BMl5BanBnXkFtZTcwNjkwMzQxNw@@._V1_SX286_.jpg',
    											  u'title': u'Battleship',
    											  u'year': 2012},
    											 {u'cert': u'R',
    											  u'id': u'21874964',
    											  u'image': u'http://ia.media-imdb.com/images/M/MV5BODcxMzY3ODY1NF5BMl5BanBnXkFtZTgwNzg1NDY4MTE@._V1_SX286_.jpg',
    											  u'title': u'Lucy',
    											  u'year': 2014},
    											 {u'cert': u'PG-13',
    											  u'id': u'20504445',
    											  u'image': u'http://ia.media-imdb.com/images/M/MV5BMTQwNjU5MzUzNl5BMl5BanBnXkFtZTYwMzc1MTI3._V1_SX286_.jpg',
    											  u'title': u'Transformers',
    											  u'year': 2007}]
    								}]}
    	 }
    												

Locker API

The Kannuu locker API is a web service that will give developers the ability to store a movie, TV show, personality, keyword, or search term into organized "locker" containers.

The API is divided into two primary definitions: Devices and Users. A device represents the physical device and may be associated with multiple users. A user represents an individual person using the system and may be associated with multiple devices. A user can in turn define 1 or more lockers to store 1 or more items, where an item is a movie, TV show, personality, keyword, or search term. Multiple lockers can be used to easily organize items of a similar nature - e.g. "watch list" or "recent searches".

GET {host}/api/2/device/token?api_key={}&op={}{?jsonp}

The host value to use is the same host value used for the lookup API calls (from the lookup configuration API) unless otherwise instructed by your Kannuu representative

Manage a device identified by a unique token value. In addition to the API_KEY, per operation parameters to include are:

create
{?id}{?name}{?image} - Create a new device token
get
{?token} - Get device details
delete
{?token} - Remove the device from the system. The device is automatically unlinked from any associated user IDs.
update
{?token}{?id}{?name}{?image} - Update device details
link
{?token}{?uid} - Link a user token ID to the device
unlink
{?token}{?uid} - Unlink a user token ID from the device
  • Parameters
  • api_key
    (required)string A customer assigned API key value. Contact your Kannuu representative to be assigned an API key.
    op
    (required)string Device operation to perform. One of ["create","get","delete","update","link","unlink"].
    token
    (required for ["get","delete","update","link","unlink"])string A unique token id value used to identify the device. If op is "create" and a token is not provided, the API will create one automatically. The token returned must be used in the other operation types.
    name
    (optional for ["create","update"])string A human readable name for the device.
    image
    (optional for ["create","update"])string A image URL resource for the device.
    id
    (optional for ["create","update"])string A client defined ID/UUID for the device (e.g. MAC address, etc.).
    uid
    (required for ["link","unlink"])string A valid user token ID to associate with the device.
    jsonp
    (optional)string Name of a JSONP callback function.
  • Response 200SHOW
  • Ex: /api/2/device/token?api_key={}&op=get&token={}

    Content-Type: application/json
    stat
    string Response status. "ok" or "fail"
    fts
    number Timestamp.
    response
    object Object containing the response result.
    token
    string Unique token ID.
    name
    string Human readable device name.
    total_results
    number Number of users associated with device.
    results
    array Array of locker summary objects.
    id
    string Unique ID of user.
    name
    string Human readable name provided at user creation.
    	{
    		"stat": "ok",
    		"fts": 1441052253137
    		"response": {
    			"name": "Living Room",
    			"token": "2234f230blbbb9b0486d3a47ae7dfc4a",
    			"total_results": 1,
    			"results": [
    				{
    					"id": "4c4f095e09035225deaade5fb9666531",
    					"name": ""
    		}
    	}
    												
GET {host}/api/2/user/token?api_key={}&op={}{?jsonp}

The host value to use is the same host value used for the lookup API calls (from the lookup configuration API) unless otherwise instructed by your Kannuu representative

Manage a user identified by a unique token value. In addition to the API_KEY, per operation parameters to include are:

create
{?name}{?image} - Create a new user token
get
{?token} - Get user locker details
devices
{?token} - Get user device association details
delete
{?token} - Remove the user from the system. The user is utomatically unlinked from any associated device IDs.
update
{?token}{?name}{?image} - Update user details
link
{?token}{?cid} - Link a client / device token ID to the user
unlink
{?token}{?cid} - Unlink a client / device token ID from the user
  • Parameters
  • api_key
    (required)string A customer assigned API key value. Contact your Kannuu representative to be assigned an API key.
    op
    (required)string User operation to perform. One of ["create","get","devices","delete","update","link","unlink"].
    token
    (required for ["get","devices","delete","update","link","unlink"])string A unique token id value used to identify the user. If op is "create" and a token is not provided, the API will create one automatically. The token returned must be used in the other operation types.
    name
    (optional for ["create","update"])string A human readable name for the user.
    image
    (optional for ["create","update"])string A image URL resource for the user.
    cid
    (required for ["link","unlink"])string A valid client / device token ID to associate with the user.
    jsonp
    (optional)string Name of a JSONP callback function.
  • Response 200SHOW
  • Ex: /api/2/user/token?api_key={}&op=devices&token={}

    Content-Type: application/json
    stat
    string Response status. "ok" or "fail"
    fts
    number Timestamp.
    response
    object Object containing the response result.
    token
    string Unique token ID.
    name
    string Human readable user name.
    devices
    number Number of devices with which the user is associated.
    results
    array Array of objects containing summary data for linked devices.
    	{
    		"stat": "ok",
    		"fts": 1441127775167
    		"response": {
    			"name": "Iam Evalin",
    			"token": "493d847caabd27cf27fe47a9748bbbc1",
    			"devices": 1,
    			"results": [
    				{
    					"id": "3345f230b1bbb9b0486d3a47ae7dfc4a",
    					"name": "Living Room"
    		}
    	}
    												
GET {host}/api/2/user/locker?api_key={}&op={}&token={}{?jsonp}

The host value to use is the same host value used for the lookup API calls (from the lookup configuration API) unless otherwise instructed by your Kannuu representative

Manage lockers for a particular user token ID. In addition to the API_KEY, per operation parameters to include are:

create
{?token}{?name}{?image}{?limit}{?type} - Create a new locker for the user
get
{?token}{?id}{?type}{?fmt}{?filter} - Get user locker item details
delete
{?token}{?id} - Remove the locker identified by "id" from the user.
update
{?token}{?id}{?name}{?image}{?limit}{?type} - Update details for locker identified by "id"
  • Parameters
  • api_key
    (required)string A customer assigned API key value. Contact your Kannuu representative to be assigned an API key.
    op
    (required)string Locker operation to perform. One of ["create","get","delete","update"].
    token
    (required)string A unique token id value used to identify the user that the locker operation is to be performed for.
    id
    (required for ["get","delete","update"])number A valid locker ID. If op is "create" the API will create one automatically. The ID returned must be used in the other operations.
    name
    (optional for ["create","update"])string A human readable name for the locker.
    image
    (optional for ["create","update"])string A image URL resource for the locker.
    type
    (required for ["create"], optional for ["get"] )string One of ["manual","auto","saved","recents","autosuggest","bookmarks"]. Generally use "manual" unless creating a specific locker type.
    jsonp
    (optional)string Name of a JSONP callback function.
  • Response 200SHOW
  • Ex: /api/2/user/locker?api_key={}&op=get&token={}&id={}

    Content-Type: application/json
    stat
    string Response status. "ok" or "fail"
    fts
    number Timestamp.
    response
    object Object containing the response result.
    locker
    object Object containing locker details.
    id
    string Unique ID of locker.
    name
    string Human readable locker name.
    limit
    number Maximum number of items locker may contain.
    total_results
    Number of items in locker.
    results
    array Array of items contained within locker. May be movie, TV show, personality, or keyword.
    	{
    		"stat": "ok",
    		"fts": 1441134624540
    		"response": {
    			"locker": {
    				"name": "Favorites",
    				"id": 2,
    				"limit": 200,
    				"type": "manual",
    				"total_results": 1,
    				"results": [
    					{
    						"id": 10058347",
    						"type": "movie:title",
    						"summary": {
    							<summary data>
    						}
    					}
    				]
    			}
    		}
    	}
    												
GET {host}/api/2/user/locker/item?api_key={}&op={}&token={}&locker={}{?jsonp}

The host value to use is the same host value used for the lookup API calls (from the lookup configuration API) unless otherwise instructed by your Kannuu representative

Manage items for a locker for a particular user token ID. In addition to the API_KEY, per operation parameters to include are:

create
{?token}{?locker}{?id}{?type} - Create a new locker item for the identified locker
get
{?token}{?locker}{?id} - Get locker item details
delete
{?token}{?locker}{?id}{?type} - Remove the locker item identified by "id" from the locker. Optionally filter on type value.
  • Parameters
  • api_key
    (required)string A customer assigned API key value. Contact your Kannuu representative to be assigned an API key.
    op
    (required)string Locker item operation to perform. One of ["create","get","delete"].
    token
    (required)string A unique token id value used to identify the user that the locker item operation is to be performed for.
    locker
    (required)number A valid locker ID.
    id
    (required)string Unique Kannuu item id. Obtained via Kannuu Lookup API.
    type
    (required for ["create"], optional for ["delete"] )string A combination of "{type}:{subtype}" where "type" is one of ['movie', 'tv', 'search'] and "subtype" is one of ['title', 'person', 'keyword', 'channel']. If subtype is not specified then "title" is assumed.
    jsonp
    (optional)string Name of a JSONP callback function.
  • Response 200SHOW
  • Ex: /api/2/user/locker/item?api_key={}&op=get&token={}&locker={}&id={}

    Content-Type: application/json
    stat
    string Response status. "ok" or "fail"
    fts
    number Timestamp.
    response
    object Object containing the response result.
    item
    object Object containing full item details as provided by the lookup API.
    	{
    		"stat": "ok",
    		"fts": 1441134624540
    		"response": {
    			"item": {
    				<full item details as provided by lookup API>
    			}
    		}
    	}
    												

Upload searchable metadata terms

Click Get Started in the navigation bar to contact Kannuu for API_Key and means of importing searchable metadata.

Resources

Here you'll find documents, user guides, and other resources granting a more in-depth look at Kannuu's APIs.

Documents

Sample Code

Click Get Started above to contact a Kannuu representative for API test access and reference javascript implementations.

Request API Key

Please complete and submit the form below to request a key for Kanuu API access.