itunes-feed

Generates and retrieves JSON feeds from iTunes for various different services. A programmatic version of the RSS Feed Generator.

Usage

Install

npm install --save itunes-feed

Example

const itunesFeed = require('itunes-feed');

// ...

try {
    let feed = await itunesFeed.appleMusic();
    console.log(`Retrieved ${feed.length} items for Apple Music`);
    
    // ...
} catch(error) {
    console.error(error);
}

API Documentation

itunes-feed ⇒ ITunesFeed

Returns: ITunesFeed - Instance of ITunesFeed.
Example

// Basic usage
const itunesFeed = require('itunes-feed');

// Advanced usage
const ITunesFeed = require('itunes-feed').ITunesFeed;
const itunesFeed = new ITunesFeed({
    // options...
});

ITunesFeed

Class exported from itunes-feed.

Kind: global class

• ITunesFeed
  • new ITunesFeed([options])
  • itunesFeed.ITunesFeed : ITunesFeed
  • itunesFeed.options : Object
  • itunesFeed.appleMusic([feedType], [options]) ⇒ Promise.<Feed>
  • itunesFeed.audioBooks([options]) ⇒ Promise.<Feed>
  • itunesFeed.books([feedType], [options]) ⇒ Promise.<Feed>
  • itunesFeed.iosApps([feedType], [genre], [options]) ⇒ Promise.<Feed>
  • itunesFeed.itunesMusic([feedType], [options]) ⇒ Promise.<Feed>
  • itunesFeed.itunesU([options]) ⇒ Promise.<Feed>
  • itunesFeed.macApps([feedType], [options]) ⇒ Promise.<Feed>
  • itunesFeed.movies([options]) ⇒ Promise.<Feed>
  • itunesFeed.musicVideos([options]) ⇒ Promise.<Feed>
  • itunesFeed.podcasts([options]) ⇒ Promise.<Feed>
  • itunesFeed.tvShows([feedType], [options]) ⇒ Promise.<Feed>

new ITunesFeed([options])

Creates a new instance of ITunesFeed.

| Param | Type | Default | Description | | --- | --- | --- | --- | | [options] | Object | {} | Optional object for configuring ITunesFeed. These options can be set on the instance (this.options). | | [options.countryCode] | String | 'us' | 2 letter country code to use for all requests. Must be lowercase. | | [options.limit] | Number | 100 | Limit of items returned in a feed. Must be one of: 10, 25, 50 or 100. Any other value will throw an error. | | [options.explicit] | Boolean | true | Whether to include explicit results. | | [options.axiosOptions] | Object | | Object containing additional options to pass to axios. |

itunesFeed.ITunesFeed : ITunesFeed

Access to uninstantiated ITunesFeed class for advanced usage.

Kind: instance property of ITunesFeed
Read only: true

itunesFeed.options : Object

Global options set on this instance. You may change these options at any time.

Kind: instance property of ITunesFeed
Example

itunesFeed.options.limit = 50;

itunesFeed.appleMusic([feedType], [options]) ⇒ Promise.<Feed>

Retrieves feed for Apple Music.

Kind: instance method of ITunesFeed
Returns: Promise.<Feed> - Instance of Feed.

| Param | Type | Default | Description | | --- | --- | --- | --- | | [feedType] | String | 'top-songs' | The type of feed to retrieve. Must be one of: coming-soon, hot-tracks, new-releases, top-albums, top-songs. | | [options] | Object | {} | Any options from ITunesFeed to overwrite for this request. |

Example

let feed = await itunesFeed.appleMusic();
//=> [...]

let feed = await itunesFeed.appleMusic('hot-tracks', {
    explicit: false
});

itunesFeed.audioBooks([options]) ⇒ Promise.<Feed>

Retrieves feed for Audiobooks.

Kind: instance method of ITunesFeed
Returns: Promise.<Feed> - Instance of Feed.

| Param | Type | Default | Description | | --- | --- | --- | --- | | [options] | Object | {} | Any options from ITunesFeed to overwrite for this request. |

Example

let feed = await itunesFeed.audioBooks();
//=> [...]

itunesFeed.books([feedType], [options]) ⇒ Promise.<Feed>

Retrieves feed for Books.

Kind: instance method of ITunesFeed
Returns: Promise.<Feed> - Instance of Feed.

| Param | Type | Default | Description | | --- | --- | --- | --- | | [feedType] | string | "'top-free'" | The type of feed to retrieve. Must be one of: top-free, top-paid. | | [options] | Object | {} | Any options from ITunesFeed to overwrite for this request. |

Example

let feed = await itunesFeed.books();
//=> [...]

itunesFeed.iosApps([feedType], [genre], [options]) ⇒ Promise.<Feed>

Retrieves feed for iOS Apps.

Kind: instance method of ITunesFeed
Returns: Promise.<Feed> - Instance of Feed.
Throws:

• Error If an invalid genre is provided.
• Error If the genre is set to games on a feed type that is not top-free or top-paid.

| Param | Type | Default | Description | | --- | --- | --- | --- | | [feedType] | string | "'top-free'" | The type of feed to retrieve. Must be one of: new-apps-we-love, new-games-we-love, top-free, top-free-ipad, top-grossing, top-grossing-ipad, top-paid. | | [genre] | string | "'all'" | Optional genre to retrieve. The only available genres are all and games. The games genre is only available on top-free and top-paid feed types. | | [options] | Object | {} | Any options from ITunesFeed to overwrite for this request. |

Example

let feed = await itunesFeed.iosApps();
//=> [...]

let feed = await itunesFeed.iosApps('top-paid', 'games');

itunesFeed.itunesMusic([feedType], [options]) ⇒ Promise.<Feed>

Retrieves feed for iTunes Music.

Kind: instance method of ITunesFeed
Returns: Promise.<Feed> - Instance of Feed.

| Param | Type | Default | Description | | --- | --- | --- | --- | | [feedType] | string | "'top-songs'" | The type of feed to retrieve. Must be one of: new-music, recent-releases, top-albums, top-songs. | | [options] | Object | {} | Any options from ITunesFeed to overwrite for this request. |

Example

let feed = await itunesFeed.itunesMusic();
//=> [...]

itunesFeed.itunesU([options]) ⇒ Promise.<Feed>

Retrieves feed for iTunes U.

Kind: instance method of ITunesFeed
Returns: Promise.<Feed> - Instance of Feed.

| Param | Type | Default | Description | | --- | --- | --- | --- | | [options] | Object | {} | Any options from ITunesFeed to overwrite for this request. |

Example

let feed = await itunesFeed.itunesU();
//=> [...]

itunesFeed.macApps([feedType], [options]) ⇒ Promise.<Feed>

Retrieves feed for MacOS Apps.

Kind: instance method of ITunesFeed
Returns: Promise.<Feed> - Instance of Feed.

| Param | Type | Default | Description | | --- | --- | --- | --- | | [feedType] | string | "'top-mac-apps'" | The type of feed to retrieve. Must be one of: top-free-mac-apps, top-grossing-mac-apps, top-mac-apps, top-paid-mac-apps. | | [options] | Object | {} | Any options from ITunesFeed to overwrite for this request. |

Example

let feed = await itunesFeed.macApps();
//=> [...]

itunesFeed.movies([options]) ⇒ Promise.<Feed>

Retrieves feed for Movies.

Kind: instance method of ITunesFeed
Returns: Promise.<Feed> - Instance of Feed.

| Param | Type | Default | Description | | --- | --- | --- | --- | | [options] | Object | {} | Any options from ITunesFeed to overwrite for this request. |

Example

let feed = await itunesFeed.movies();
//=> [...]

itunesFeed.musicVideos([options]) ⇒ Promise.<Feed>

Retrieves feed for Music Videos.

Kind: instance method of ITunesFeed
Returns: Promise.<Feed> - Instance of Feed.

| Param | Type | Default | Description | | --- | --- | --- | --- | | [options] | Object | {} | Any options from ITunesFeed to overwrite for this request. |

Example

let feed = await itunesFeed.musicVideos();
//=> [...]

itunesFeed.podcasts([options]) ⇒ Promise.<Feed>

Retrieves feed for Podcasts.

Kind: instance method of ITunesFeed
Returns: Promise.<Feed> - Instance of Feed.

| Param | Type | Default | Description | | --- | --- | --- | --- | | [options] | Object | {} | Any options from ITunesFeed to overwrite for this request. |

Example

let feed = await itunesFeed.podcasts();
//=> [...]

itunesFeed.tvShows([feedType], [options]) ⇒ Promise.<Feed>

Retrieves feed for TV Shows.

Kind: instance method of ITunesFeed
Returns: Promise.<Feed> - Instance of Feed.

| Param | Type | Default | Description | | --- | --- | --- | --- | | [feedType] | string | "'top-tv-episodes'" | The type of feed to retrieve. Must be one of: top-tv-episodes, top-tv-seasons. | | [options] | Object | {} | Any options from ITunesFeed to overwrite for this request. |

Example

let feed = await itunesFeed.tvShows();
//=> [...]

Feed ⇐ Array

Data wrapper for feed responses. Returns an array of results from the feed with additional properties available on the prototype.

Kind: global class
Extends: Array

• Feed ⇐ Array
  • feed.title : String
  • feed.url : String
  • feed.countryCode : String
  • feed.updated : Date

feed.title : String

The title of the feed.

Kind: instance property of Feed
Read only: true

feed.url : String

The url of the feed.

Kind: instance property of Feed
Read only: true

feed.countryCode : String

The country code in which this feed is for.

Kind: instance property of Feed
Read only: true

feed.updated : Date

The date when this feed was last updated.

Kind: instance property of Feed
Read only: true

Tests

To run tests locally, clone this repo and run:

npm test

License

MIT License