node package manager


Cache iTunes search

Build Status Coverage Status


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



A function applied to each result.

The default, lib/element.js, interprets results as podcasts:

  • author String
  • feed String
  • guid Number
  • img100 String
  • img30 String
  • img60 String
  • img600 String
  • title String
  • updated Number
  • ts Number


The options for the fanboy cache:

  • cacheSize Number The cache size passed to levelup.
  • country String The country code for the search API—defaults to 'us'.
  • highWaterMark Number Passed to stream.Readable constructor.
  • hostname String The host name of the store ('').
  • media String The media type to search for ('all').
  • objectMode Boolean Whether this stream should behave as a stream of objects (false).
  • path String The path to the store (/search).
  • port Number The port to access the store (80).
  • reduce reduce()
  • ttl Number Time to live in milliseconds (24 * 3600 * 1000).


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').

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', {
  type: 'podcast'

Searching the cache

const search =
search.end('merlin mann')

To run this printing only the title(s), do:

$ node example/search | json -ga title

This will search remotely and cache the result, subsequent requests will use the cache.

Looking up a guid

const lookup = cache.lookup()

You can run this with:

$ node example/lookup | json

Getting 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.

Overriding stream options

The search, lookup, and suggest functions accept an optional stream options Object that lets you override global stream options—highWaterMark, encoding, and objectMode—of your fanboy instance.


With npm, do:

$ npm install fanboy


MIT License