Security News
The Dark Side of Open Source
At Node Congress, Socket CEO Feross Aboukhadijeh uncovers the darker aspects of open source, where applications that rely heavily on third-party dependencies can be exploited in supply chain attacks.
node-itunes-search
Advanced tools
Readme
A simple NodeJS wrapper for the ITunes Search API.
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.
$ npm install node-itunes-search
const itunesAPI = require("node-itunes-search");
import {ItunesSearchOptions} from "node-itunes-search";
import ItunesSearch from "node-itunes-search";
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);
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);
});
import ItunesSearch from "node-itunes-search";
const lookupOptions: ItunesSearch.LookupOptionsInterface = {
keys: ["560857776"],
keyType: ItunesSearch.LookupType.ID
};
const result: ItunesSearch.Result = await ItunesSearch.lookup(lookupOptions);
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.
ISearchOptions
The structure for an options object required when calling the searchItunes
function.
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
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.
Type | Member |
---|---|
ItunesWrapperType | wrapperType |
ItunesKind | kind |
ItunesExplicitness | collectionExplicitness |
ItunesExplicitness | trackExplicitness |
boolean | isStreamable |
object | raw |
number | artistId |
number | collectionId |
number | trackId |
number | collectionPrice |
number | trackPrice |
number | discCount |
number | discNumber |
number | trackCount |
number | trackNumber |
number | trackTimeMillis |
string | artistName |
string | collectionName |
string | trackName |
string | collectionCensoredName |
string | trackCensoredName |
string | artistViewUrl |
string | collectionViewUrl |
string | trackViewUrl |
string | previewUrl |
string | artworkUrl30 |
string | artworkUrl60 |
string | artworkUrl100 |
string | releaseDate |
string | country |
string | currency |
string | primaryGenreName |
ItunesResult
The returned metadata of a searchItunes
or lookupItunes
query.
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
.
ItunesLookupType
Key | Value |
---|---|
ID | "id" |
AMGARTISTID | "amgArtistId" |
AMGALBUMID | "amgAlbumId" |
AMGVIDEOID | "amgVideoId" |
UPC | "upc" |
ISBN | "isbn" |
ItunesExplicitness
Key | Value |
---|---|
Explicit | "explicit" |
Cleaned | "cleaned" |
NotExplicit | "notExplicit" |
ItunesKind
Key | Value |
---|---|
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
Key | Value |
---|---|
Track | "track" |
Collection | "collection" |
Artist | "artist" |
ItunesMedia
Key | Value |
---|---|
Movie | "movie" |
Podcast | "podcast" |
Music | "music" |
MusicVideo | "musicVideo" |
AudioBook | "audiobook" |
ShortFilm | "shortFilm" |
TvShow | "tvShow" |
Software | "software" |
Ebook | "ebook" |
All | "all" |
ItunesEntityMovie
Key | Value |
---|---|
MovieArtist | "movieArtist" |
Movie | "movie" |
ItunesEntityPodcast
Key | Value |
---|---|
PodcastAuthor | "podcastAuthor" |
Podcast | "podcast" |
ItunesEntityMusic
Key | Value |
---|---|
MusicArtist | "musicArtist" |
MusicTrack | "musicTrack" |
Album | "album" |
MusicVideo | "musicVideo" |
Mix | "mix" |
Song | "song" |
ItunesEntityMusicVideo
Key | Value |
---|---|
MusicArtist | "musicArtist" |
MusicVideo | "musicVideo" |
ItunesEntityAudioBook
Key | Value |
---|---|
AudioBookAuthor | "audiobookAuthor" |
AudioBook | "audiobook" |
ItunesEntityShortFilm
Key | Value |
---|---|
ShortFilmArtist | "shortFilmArtist" |
ShortFilm | "shortFilm" |
ItunesEntityTvShow
Key | Value |
---|---|
TvEpisode | "tvEpisode" |
TvSeason | "tvSeason" |
ItunesEntitySoftware
Key | Value |
---|---|
Software | "software" |
IPadSoftware | "iPadSoftware" |
MacSoftware | "macSoftware" |
ItunesEntityEbook
Key | Value |
---|---|
Ebook | "ebook" |
ItunesEntityAll
Key | Value |
---|---|
Movie | "movie" |
Album | "album" |
AllArtist | "allArtist" |
Podcast | "podcast" |
MusicVideo | "musicVideo" |
Mix | "mix" |
AudioBook | "audiobook" |
TvSeason | "tvSeason" |
AllTrack | "allTrack" |
searchItunes
lookupItunes
node-itunes-search
exports a single default namespace ItunesSearch
. This is an alternative to referencing all models the package exports.
Type | Model | Namespace Alias |
---|---|---|
Global Variable | itunesSearchRoot | SearchRoot |
Global Variable | itunesLookupRoot | LookupRoot |
Interface | ISearchOptions | SearchOptionsInterface |
Interface | ILookupOptions | LookupOptionsInterface |
Class | ItunesSearchOptions | SearchOptions |
Class | ItunesLookupOptions | LookupOptions |
Class | ItunesProperties | Properties |
Class | ItunesResult | Result |
Enum | ItunesLookupType | LookupType |
Enum | ItunesExplicitness | Explicitness |
Enum | ItunesKind | Kind |
Enum | ItunesWrapperType | WrapperType |
Enum | ItunesMedia | Media |
Enum | ItunesEntityMovie | Entity.Movie |
Enum | ItunesEntityPodcast | Entity.Podcast |
Enum | ItunesEntityMusic | Entity.Music |
Enum | ItunesEntityMusicVideo | Entity.MusicVideo |
Enum | ItunesEntityAudioBook | Entity.AudioBook |
Enum | ItunesEntityShortFilm | Entity.ShortFilm |
Enum | ItunesEntityTvShow | Entity.TvShow |
Enum | ItunesEntitySoftware | Entity.Software |
Enum | ItunesEntityEbook | Entity.Ebook |
Enum | ItunesEntityAll | Entity.All |
Function | searchItunes | search |
Function | lookupItunes | lookup |
Note: Since the ItunesSearch
namespace is the default
export of the package, using the name ItunesSearch
is optional.
Description | Statement | Result |
---|---|---|
TypeScript import | import ItunesSearch from "node-itunes-search"; | Success |
Default import | import 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 |
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!
Look in the examples directory for usage examples.
FAQs
A simple NodeJS wrapper for the ITunes Search API.
The npm package node-itunes-search receives a total of 78 weekly downloads. As such, node-itunes-search popularity was classified as not popular.
We found that node-itunes-search demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
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.
Security News
At Node Congress, Socket CEO Feross Aboukhadijeh uncovers the darker aspects of open source, where applications that rely heavily on third-party dependencies can be exploited in supply chain attacks.
Research
Security News
The Socket Research team found this npm package includes code for collecting sensitive developer information, including your operating system username, Git username, and Git email.
Security News
OpenJS is warning of social engineering takeovers targeting open source projects after receiving a credible attempt on the foundation.