Socket
Socket
Sign inDemoInstall

node-itunes-search

Package Overview
Dependencies
1
Maintainers
1
Versions
25
Alerts
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

node-itunes-search


Version published
Weekly downloads
283
increased by18.41%
Maintainers
1
Created
Weekly downloads
 

Readme

Source

node-itunes-search npm Build Status

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

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

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);
});
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.

TypeMember
ItunesWrapperTypewrapperType

ItunesKindkind

ItunesExplicitnesscollectionExplicitness
ItunesExplicitnesstrackExplicitness

booleanisStreamable

objectraw

numberartistId
numbercollectionId
numbertrackId
numbercollectionPrice
numbertrackPrice
numberdiscCount
numberdiscNumber
numbertrackCount
numbertrackNumber
numbertrackTimeMillis

stringartistName
stringcollectionName
stringtrackName
stringcollectionCensoredName
stringtrackCensoredName
stringartistViewUrl
stringcollectionViewUrl
stringtrackViewUrl
stringpreviewUrl
stringartworkUrl30
stringartworkUrl60
stringartworkUrl100
stringreleaseDate
stringcountry
stringcurrency
stringprimaryGenreName
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
KeyValue
ID"id"
AMGARTISTID"amgArtistId"
AMGALBUMID"amgAlbumId"
AMGVIDEOID"amgVideoId"
UPC"upc"
ISBN"isbn"
ItunesExplicitness
KeyValue
Explicit"explicit"
Cleaned"cleaned"
NotExplicit"notExplicit"
ItunesKind
KeyValue
Book"book"
Album"album"
CoachedAudio"coached-audio"
FeatureMovie"feature-movie"
InteractiveBooklet"interactive-booklet"
MusicVideo"music-video"
PdfPodcast"pdf podcast"
PodcastEpisode"podcast-episode"
SoftwarePackage"software-package"
Song"song"
TvEpisode"tv-episode"
Artist"artist"
ItunesWrapperType
KeyValue
Track"track"
Collection"collection"
Artist"artist"
ItunesMedia
KeyValue
Movie"movie"
Podcast"podcast"
Music"music"
MusicVideo"musicVideo"
AudioBook"audiobook"
ShortFilm"shortFilm"
TvShow"tvShow"
Software"software"
Ebook"ebook"
All"all"
ItunesEntityMovie
KeyValue
MovieArtist"movieArtist"
Movie"movie"
ItunesEntityPodcast
KeyValue
PodcastAuthor"podcastAuthor"
Podcast"podcast"
ItunesEntityMusic
KeyValue
MusicArtist"musicArtist"
MusicTrack"musicTrack"
Album"album"
MusicVideo"musicVideo"
Mix"mix"
Song"song"
ItunesEntityMusicVideo
KeyValue
MusicArtist"musicArtist"
MusicVideo"musicVideo"
ItunesEntityAudioBook
KeyValue
AudioBookAuthor"audiobookAuthor"
AudioBook"audiobook"
ItunesEntityShortFilm
KeyValue
ShortFilmArtist"shortFilmArtist"
ShortFilm"shortFilm"
ItunesEntityTvShow
KeyValue
TvEpisode"tvEpisode"
TvSeason"tvSeason"
ItunesEntitySoftware
KeyValue
Software"software"
IPadSoftware"iPadSoftware"
MacSoftware"macSoftware"
ItunesEntityEbook
KeyValue
Ebook"ebook"
ItunesEntityAll
KeyValue
Movie"movie"
Album"album"
AllArtist"allArtist"
Podcast"podcast"
MusicVideo"musicVideo"
Mix"mix"
AudioBook"audiobook"
TvSeason"tvSeason"
AllTrack"allTrack"

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
TypeModelNamespace Alias
Global VariableitunesSearchRootSearchRoot
Global VariableitunesLookupRootLookupRoot

InterfaceISearchOptionsSearchOptionsInterface
InterfaceILookupOptionsLookupOptionsInterface

ClassItunesSearchOptionsSearchOptions
ClassItunesLookupOptionsLookupOptions
ClassItunesPropertiesProperties
ClassItunesResultResult

EnumItunesLookupTypeLookupType
EnumItunesExplicitnessExplicitness
EnumItunesKindKind
EnumItunesWrapperTypeWrapperType
EnumItunesMediaMedia
EnumItunesEntityMovieEntity.Movie
EnumItunesEntityPodcastEntity.Podcast
EnumItunesEntityMusicEntity.Music
EnumItunesEntityMusicVideoEntity.MusicVideo
EnumItunesEntityAudioBookEntity.AudioBook
EnumItunesEntityShortFilmEntity.ShortFilm
EnumItunesEntityTvShowEntity.TvShow
EnumItunesEntitySoftwareEntity.Software
EnumItunesEntityEbookEntity.Ebook
EnumItunesEntityAllEntity.All

FunctionsearchItunessearch
FunctionlookupItuneslookup

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

Example
DescriptionStatementResult
TypeScript importimport ItunesSearch from "node-itunes-search";Success
Default importimport ItunesSearch from "node-itunes-search";Success
Default import (custom identifier)import NodeItunesSearch from "node-itunes-search";Success

TypeScript import (non-existent identifier)import {NodeItunesSearch} from "node-itunes-search";Fail

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.

Keywords

FAQs

Last updated on 18 Mar 2022

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Packages

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc