node package manager
We need your input. Help make JavaScript better: Take the 2017 JavaScript Ecosystem survey »


Build Status Coverage Status


The fanboy Node.js package implements proxy caching for parts of the iTunes Search API.



null or undefined.


A map or filter callback applied with each JSON result obj.

Returns result or void().

The default callback adds the required guid property to obj and returns it. For production I’d return a classy object.


The options for the fanboy cache:

  • cacheSize = 1024 * 1024 * 8 The cache size passed to levelup.
  • country = 'us' The country code for the search API.
  • highWaterMark Number Passed to stream.Readable constructor.
  • hostname = '' The host name of the store.
  • media = 'all' The media type to search for.
  • objectMode = false Whether this stream should behave as a stream of objects.
  • path = '/search' The path to the store.
  • port = 80 The port to access the store.
  • result result()
  • ttl = 24 * 3600 * 1000 Time in milliseconds before cached items go stale.


The fanboy module exports a single function that returns a new cache object (an instance of the Fanboy class). To access the Fanboy class require('fanboy'). fanboy streams do not validate or modify search terms written to them. Be aware that term validation is expected to be dealt with upstream.

Creating a new cache

fanboy(name, opts)

  • name String The name of the file system directory for the database.
  • opts opts() Optional parameters of the cache.
const fanboy = require('fanboy')
const cache = fanboy('/tmp/fanboy.db', {
  media: 'podcast'

Searching the cache

const search =

Try running this with something like:

$ node example/search | json -ga collectionId

This will search remotely and cache the result. Until the term expires, subsequent requests hit the cache.

Looking up a guid

const lookup = cache.lookup()

You can run this with:

$ node example/lookup | json

Obtaining suggestions for search terms

const suggest = cache.suggest()


$ node example/suggest | json

If you have not searched before doing this, you will not get any results, because the suggestions index is populated as we are caching data. Pass a Number to limit the number of suggestions retrieved.


The default limit of items emitted per term through this API is 50.


With npm, do:

$ npm install fanboy


MIT License