node-itunes-search v1.2.3

node-itunes-search

A simple NodeJS wrapper for the ITunes Search API.

What?

The iTunes Search API is a publicly available API hosted by Apple which streams Metadata. This wrapper uses the phin npm package to make HTTP requests to the API.

• Installation
• Importing
• Usage
• API
• Contributing
• Examples

Installation

$ npm install node-itunes-search

Importing

Commonjs

const itunesAPI = require("node-itunes-search");

ES6

import {ItunesSearchOptions} from "node-itunes-search";

Default Namespace

import ItunesSearch from "node-itunes-search";

Usage

The module exposes 2 functions searchItunes and lookupItunes which can be used to search and lookup content using the Itunes Search API respectively.

Both of these functions use vanilla javascript promises which, when successful, will return an ItunesResult.

Note Versions 1.2.0 and higher now have a simpler syntax.

Search

const itunesAPI = require("node-itunes-search");

const searchOptions = new itunesAPI.ItunesSearchOptions({
  term: "Queen Bohemian Rhapsody", // All searches require a single string query.

  limit: 1 // An optional maximum number of returned results may be specified.
});

itunesAPI.searchItunes(searchOptions).then((result) => {
  console.log(result);
});

Simple Search

const itunesApi = require("node-itunes-search");

const searchOptions = {
  term: "Queen Bohemian Rhapsody",
  limit: 1
};

const result = await itunesApi.searchItunes(searchOptions);

Lookup

import {
  lookupItunes,
  ItunesResult,
  ItunesLookupOptions,
  ItunesLookupType
} from "node-itunes-search";

const lookupOptions = new ItunesLookupOptions({
  keys: ["560857776"], // Specify ID(s) of desired content
  keyType: ItunesLookupType.ID // Searching by content ID(s)
});

lookupItunes(lookupOptions).then((result: ItunesResult) => {
  console.log(result);
});

Simple Lookup

import ItunesSearch from "node-itunes-search";

const lookupOptions: ItunesSearch.LookupOptionsInterface = {
  keys: ["560857776"],
  keyType: ItunesSearch.LookupType.ID
};

const result: ItunesSearch.Result = await ItunesSearch.lookup(lookupOptions);

API

Global Variables

const itunesSearchRoot: string

The root domain used when making search queries using the searchItunes function.

const itunesLookupRoot: string

The root domain used when making lookup queries using the lookupItunes function.

Interfaces

ISearchOptions

The structure for an options object required when calling the searchItunes function.

Members

term: string

The string query for the search request. For example if your looking for a particular song, using the format "ARTIST_NAME SONG_NAME" may return more accurate results.

country?: string

A 2 character string representing an ISO 3166 code.

For example, to specify "United States" use "US".

Please refer to the following URL for other country codes: https://en.m.wikipedia.org/wiki/ISO_3166-1_alpha-2

media?: ItunesMedia

entity?: ItunesEntityMovie | ItunesEntityPodcast | ItunesEntityMusic | ItunesEntityMusicVideo | ItunesEntityAudioBook | ItunesEntityShortFilm | ItunesEntityTvShow | ItunesEntitySoftware | ItunesEntityEbook | ItunesEntityAll

limit?: number

lang?: "en_us" | "ja_jp"

extras?: {}

A JSON object containing any custom query properties to be included in the search.

This is useful when a property is missing from ISearchOptions.

toURI?: () => string

ILookupOptions

The structure for an options object required when calling the lookupItunes function.

keys: Array<string>

keyType: ItunesLookupType

entity?: ItunesEntityMovie | ItunesEntityPodcast | ItunesEntityMusic | ItunesEntityMusicVideo | ItunesEntityAudioBook | ItunesEntityShortFilm | ItunesEntityTvShow | ItunesEntitySoftware | ItunesEntityEbook | ItunesEntityAll

limit?: number

extras?: {}

A JSON object containing any custom query properties to be included in the search.

This is useful when a property is missing from ILookupOptions.

toURI?: () => string

Classes

ItunesSearchOptions

ItunesLookupOptions

ItunesProperties

All the properties of a single result from a searchItunes or lookupItunes query.

Each ItunesProperties also comes with a raw property. This is an exact copy of the result without enforcing any types. The raw property is especially useful when a needed result property is missing from the ItunesProperties class.

ItunesResult

The returned metadata of a searchItunes or lookupItunes query.

Members

const results: Array<ItunesProperties>

An Array of ItunesProperties objects parsed from the result of a searchItunes or lookupItunes query.

const resultCount: number

The total number of results.

Enums

ItunesLookupType

ItunesExplicitness

ItunesKind

ItunesWrapperType

ItunesMedia

ItunesEntityMovie

ItunesEntityPodcast

ItunesEntityMusic

ItunesEntityMusicVideo

ItunesEntityAudioBook

ItunesEntityShortFilm

ItunesEntityTvShow

ItunesEntitySoftware

ItunesEntityEbook

ItunesEntityAll

Functions

searchItunes

lookupItunes

Namespace

node-itunes-search exports a single default namespace ItunesSearch. This is an alternative to referencing all models the package exports.

Aliases

Note: Since the ItunesSearch namespace is the default export of the package, using the name ItunesSearch is optional.

Example

Contributing

Feel free to make an issue or pull request. My schedule is pretty open and I will be more than happy to review any requests or answer any questions you may have!

Examples

Look in the examples directory for usage examples.