https://github.com/kyleross/node-itunes-feed

iTunes Feed generator and crawler for Node
https://github.com/kyleross/node-itunes-feed
Last synced: about 1 year ago
JSON representation
iTunes Feed generator and crawler for Node
Host: GitHub
URL: https://github.com/kyleross/node-itunes-feed
Owner: KyleRoss
License: mit
Created: 2019-04-17T16:56:33.000Z (over 7 years ago)
Default Branch: master
Last Pushed: 2024-03-15T20:10:20.000Z (over 2 years ago)
Last Synced: 2024-10-30T00:44:40.898Z (over 1 year ago)
Language: JavaScript
Size: 34.2 KB
Stars: 4
Watchers: 2
Forks: 1
Open Issues: 8
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project

README

          # itunes-feed

[![npm](https://img.shields.io/npm/v/itunes-feed.svg?style=for-the-badge)](https://www.npmjs.com/package/itunes-feed)

[![npm](https://img.shields.io/npm/dt/itunes-feed.svg?style=for-the-badge)](https://www.npmjs.com/package/itunes-feed)

[![David](https://img.shields.io/david/KyleRoss/node-itunes-feed.svg?style=for-the-badge)](https://david-dm.org/KyleRoss/node-itunes-feed)

[![Travis](https://img.shields.io/travis/KyleRoss/node-itunes-feed/master.svg?style=for-the-badge)](https://travis-ci.org/KyleRoss/node-itunes-feed)

[![Coveralls](https://img.shields.io/coveralls/github/KyleRoss/node-itunes-feed.svg?style=for-the-badge)](https://coveralls.io/github/KyleRoss/node-itunes-feed)

[![license](https://img.shields.io/github/license/KyleRoss/node-itunes-feed.svg?style=for-the-badge)](https://github.com/KyleRoss/node-itunes-feed/blob/master/LICENSE)

[![Beerpay](https://img.shields.io/beerpay/KyleRoss/node-itunes-feed.svg?style=for-the-badge)](https://beerpay.io/KyleRoss/node-itunes-feed)

Generates and retrieves JSON feeds from iTunes for various different services. A programmatic version of the [RSS Feed Generator](https://rss.itunes.apple.com/en-us).

# Usage

## Install

```

npm install --save itunes-feed

```

## Example

```js

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](#ITunesFeed)

**Returns**: [ITunesFeed](#ITunesFeed) - Instance of ITunesFeed.  

**Example**  

```js

// 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](#ITunesFeed)

    * [new ITunesFeed([options])](#new_ITunesFeed_new)

    * [itunesFeed.ITunesFeed](#ITunesFeed+ITunesFeed) : [ITunesFeed](#ITunesFeed)

    * [itunesFeed.options](#ITunesFeed+options) : Object

    * [itunesFeed.appleMusic([feedType], [options])](#ITunesFeed+appleMusic) ⇒ [Promise.<Feed>](#Feed)

    * [itunesFeed.audioBooks([options])](#ITunesFeed+audioBooks) ⇒ [Promise.<Feed>](#Feed)

    * [itunesFeed.books([feedType], [options])](#ITunesFeed+books) ⇒ [Promise.<Feed>](#Feed)

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

    * [itunesFeed.itunesMusic([feedType], [options])](#ITunesFeed+itunesMusic) ⇒ [Promise.<Feed>](#Feed)

    * [itunesFeed.itunesU([options])](#ITunesFeed+itunesU) ⇒ [Promise.<Feed>](#Feed)

    * [itunesFeed.macApps([feedType], [options])](#ITunesFeed+macApps) ⇒ [Promise.<Feed>](#Feed)

    * [itunesFeed.movies([options])](#ITunesFeed+movies) ⇒ [Promise.<Feed>](#Feed)

    * [itunesFeed.musicVideos([options])](#ITunesFeed+musicVideos) ⇒ [Promise.<Feed>](#Feed)

    * [itunesFeed.podcasts([options])](#ITunesFeed+podcasts) ⇒ [Promise.<Feed>](#Feed)

    * [itunesFeed.tvShows([feedType], [options])](#ITunesFeed+tvShows) ⇒ [Promise.<Feed>](#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](https://github.com/axios/axios#request-config). |



### itunesFeed.ITunesFeed : [ITunesFeed](#ITunesFeed)

Access to uninstantiated ITunesFeed class for advanced usage.

**Kind**: instance property of [ITunesFeed](#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](#ITunesFeed)  

**Example**  

```js

itunesFeed.options.limit = 50;

```



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

Retrieves feed for Apple Music.

**Kind**: instance method of [ITunesFeed](#ITunesFeed)  

**Returns**: [Promise.<Feed>](#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**  

```js

let feed = await itunesFeed.appleMusic();

//=> [...]

let feed = await itunesFeed.appleMusic('hot-tracks', {

    explicit: false

});

```



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

Retrieves feed for Audiobooks.

**Kind**: instance method of [ITunesFeed](#ITunesFeed)  

**Returns**: [Promise.<Feed>](#Feed) - Instance of `Feed`.  

| Param | Type | Default | Description |

| --- | --- | --- | --- |

| [options] | Object | {} | Any options from ITunesFeed to overwrite for this request. |

**Example**  

```js

let feed = await itunesFeed.audioBooks();

//=> [...]

```



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

Retrieves feed for Books.

**Kind**: instance method of [ITunesFeed](#ITunesFeed)  

**Returns**: [Promise.<Feed>](#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**  

```js

let feed = await itunesFeed.books();

//=> [...]

```



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

Retrieves feed for iOS Apps.

**Kind**: instance method of [ITunesFeed](#ITunesFeed)  

**Returns**: [Promise.<Feed>](#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**  

```js

let feed = await itunesFeed.iosApps();

//=> [...]

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

```



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

Retrieves feed for iTunes Music.

**Kind**: instance method of [ITunesFeed](#ITunesFeed)  

**Returns**: [Promise.<Feed>](#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**  

```js

let feed = await itunesFeed.itunesMusic();

//=> [...]

```



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

Retrieves feed for iTunes U.

**Kind**: instance method of [ITunesFeed](#ITunesFeed)  

**Returns**: [Promise.<Feed>](#Feed) - Instance of `Feed`.  

| Param | Type | Default | Description |

| --- | --- | --- | --- |

| [options] | Object | {} | Any options from ITunesFeed to overwrite for this request. |

**Example**  

```js

let feed = await itunesFeed.itunesU();

//=> [...]

```



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

Retrieves feed for MacOS Apps.

**Kind**: instance method of [ITunesFeed](#ITunesFeed)  

**Returns**: [Promise.<Feed>](#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**  

```js

let feed = await itunesFeed.macApps();

//=> [...]

```



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

Retrieves feed for Movies.

**Kind**: instance method of [ITunesFeed](#ITunesFeed)  

**Returns**: [Promise.<Feed>](#Feed) - Instance of `Feed`.  

| Param | Type | Default | Description |

| --- | --- | --- | --- |

| [options] | Object | {} | Any options from ITunesFeed to overwrite for this request. |

**Example**  

```js

let feed = await itunesFeed.movies();

//=> [...]

```



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

Retrieves feed for Music Videos.

**Kind**: instance method of [ITunesFeed](#ITunesFeed)  

**Returns**: [Promise.<Feed>](#Feed) - Instance of `Feed`.  

| Param | Type | Default | Description |

| --- | --- | --- | --- |

| [options] | Object | {} | Any options from ITunesFeed to overwrite for this request. |

**Example**  

```js

let feed = await itunesFeed.musicVideos();

//=> [...]

```



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

Retrieves feed for Podcasts.

**Kind**: instance method of [ITunesFeed](#ITunesFeed)  

**Returns**: [Promise.<Feed>](#Feed) - Instance of `Feed`.  

| Param | Type | Default | Description |

| --- | --- | --- | --- |

| [options] | Object | {} | Any options from ITunesFeed to overwrite for this request. |

**Example**  

```js

let feed = await itunesFeed.podcasts();

//=> [...]

```



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

Retrieves feed for TV Shows.

**Kind**: instance method of [ITunesFeed](#ITunesFeed)  

**Returns**: [Promise.<Feed>](#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**  

```js

let feed = await itunesFeed.tvShows();

//=> [...]

```



## Feed ⇐ [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)  

* [Feed](#Feed) ⇐ [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)

    * [feed.title](#Feed+title) : String

    * [feed.url](#Feed+url) : String

    * [feed.countryCode](#Feed+countryCode) : String

    * [feed.updated](#Feed+updated) : Date



### feed.title : String

The title of the feed.

**Kind**: instance property of [Feed](#Feed)  

**Read only**: true  



### feed.url : String

The url of the feed.

**Kind**: instance property of [Feed](#Feed)  

**Read only**: true  



### feed.countryCode : String

The country code in which this feed is for.

**Kind**: instance property of [Feed](#Feed)  

**Read only**: true  



### feed.updated : Date

The date when this feed was last updated.

**Kind**: instance property of [Feed](#Feed)  

**Read only**: true  

## Tests

To run tests locally, clone this repo and run:

```

npm test

```

## License

MIT License
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/kyleross/node-itunes-feed

Awesome Lists containing this project

README
