# node-itunes-search > A wrapper around the iTunes Search API Latest version **3.0.0** (published 2024-09-24) · MIT license · 0 weekly downloads ## Install ```sh npm install node-itunes-search pnpm add node-itunes-search yarn add node-itunes-search bun add node-itunes-search ``` ## Health **Score 45/100 (D)** — status: stable. Positive: has types; no vulnerabilities; high quality score. Warnings: low downloads; no esm support. Negative: stale. ## Facts | | | |---|---| | Version | 3.0.0 | | Published | 2024-09-24 | | First published | 2018-10-26 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | CommonJS | | Node | >=18.0.0 | | Dependencies | 0 | | Unpacked size | 47 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 27 | | Author | Jacob Shuman | | Maintainers | jacob.shuman | | Keywords | itunes, search, api | ## Links - npm: https://www.npmjs.com/package/node-itunes-search - Repository: https://github.com/jacob-shuman/node-itunes-search - Homepage: https://github.com/jacob-shuman/node-itunes-search#readme - Issues: https://github.com/jacob-shuman/node-itunes-search/issues - npm.io page: https://npm.io/package/node-itunes-search ## Alternatives - [jsforce](https://npm.io/package/jsforce.md) — 851.2K weekly downloads - [react-native-qrcode-svg](https://npm.io/package/react-native-qrcode-svg.md) — 693.5K weekly downloads - [@salesforce/plugin-data](https://npm.io/package/@salesforce/plugin-data.md) — 394.9K weekly downloads - [@backstage/plugin-search-common](https://npm.io/package/@backstage/plugin-search-common.md) — 308.5K weekly downloads - [@chain-registry/types](https://npm.io/package/@chain-registry/types.md) — 38.4K weekly downloads ## Recent versions - 3.0.0 (latest) — 2024-09-24 - 2.0.0 — 2024-09-20 - 1.2.3 — 2022-03-18 - 1.2.2 — 2019-01-24 - 1.2.1 — 2019-01-08 - 1.2.0 — 2019-01-07 - 1.1.0 — 2018-11-18 - 1.0.2 — 2018-11-08 - 1.0.1 — 2018-11-08 - 1.0.0 — 2018-11-08 - 0.6.1 — 2018-11-02 - 0.6.0 — 2018-11-02 - 0.5.0 — 2018-10-30 - 0.4.2 — 2018-10-28 - 0.4.1 — 2018-10-28 - … 12 more at https://npm.io/package/node-itunes-search/versions ## README # `node-itunes-search` > A wrapper around the [iTunes Search API](https://developer.apple.com/library/archive/documentation/AudioVideo/Conceptual/iTuneSearchAPI/index.html#//apple_ref/doc/uid/TP40017632-CH3-SW1) > > _"The Search API allows you to place search fields in your website to search for content within the iTunes Store, App Store, iBooks Store and Mac App Store."_ ## Installation npm badge ```bash npm install node-itunes-search ``` jsr badge ```bash npx jsr add @nullbitme/search-itunes ``` ## Usage This module exposes 2 functions `searchItunes` and `lookupItunes` which can be used to search and lookup content using the Itunes Search API respectively. Both functions return a promise for a `ItunesResults` object with the following structure: ```ts interface ItunesResults { resultCount: number; // Results of search/lookup results: (ItunesResult & { [key: string]: unknown })[]; } interface ItunesResults { wrapperType?: ItunesWrapperType; kind?: ItunesKind; artistId?: number; collectionId?: number; trackId?: number; artistName?: string; collectionName: string; trackName?: string; collectionCensoredName?: string; trackCensoredName?: string; collectionArtistId?: string; collectionArtistViewUrl?: string; artistViewUrl?: string; collectionViewUrl?: string; trackViewUrl?: string; previewUrl?: string; artworkUrl30?: string; artworkUrl60?: string; artworkUrl100?: string; trackRentalPrice?: number; trackHdRentalPrice?: number; collectionPrice?: number; trackPrice?: number; releaseDate?: string; collectionExplicitness?: ItunesExplicitness; trackExplicitness?: ItunesExplicitness; discCount?: number; discNumber?: number; trackCount?: number; trackNumber?: number; trackTimeMillis?: number; country?: string; currency?: string; primaryGenreName?: string; contentAdvisoryRating?: string; shortDescription?: string; longDescription?: string; isStreamable?: boolean; hasITunesExtras?: boolean; } ``` This is **not** an exhaustive list of all possible properties on an `ItunesResult` due to the _limited_ api documentation. `ItunesResult` contains many of the most common properties that _could_ be on a result after reading the documentation and a bit of experimentation. ### Search [Search for content using the Itunes Search API. This function requires a `term` string to perform a search.](https://developer.apple.com/library/archive/documentation/AudioVideo/Conceptual/iTuneSearchAPI/Searching.html#//apple_ref/doc/uid/TP40017632-CH5-SW1) ```ts async function searchItunes( options: ItunesSearchOptions ): Promise; ``` ### Lookup [_"You can also create a lookup request to search for content in the stores based on iTunes IDs, UPCs/ EANs, and All Music Guide (AMG) IDs. ID-based lookups are faster and contain fewer false-positive results."_](https://developer.apple.com/library/archive/documentation/AudioVideo/Conceptual/iTuneSearchAPI/LookupExamples.html#//apple_ref/doc/uid/TP40017632-CH7-SW1) ```ts async function lookupItunes( options: ItunesLookupOptions ): Promise; ``` ## Examples ### Song Search ```ts // npm import { searchItunes } from "node-itunes-search"; // jsr import { searchItunes } from "@nullbitme/search-itunes"; const results = await searchItunes({ // Search Query term: "Queen Bohemian Rhapsody", // Setting max number of results to 2 limit: 2, }); console.log(results); ``` ```json { "resultCount": 2, "results": [ { "wrapperType": "track", "kind": "song", "artistId": 3296287, "collectionId": 1434899831, "trackId": 1434899925, "artistName": "Queen", "collectionName": "Bohemian Rhapsody (The Original Soundtrack)", "trackName": "Killer Queen", "collectionCensoredName": "Bohemian Rhapsody (The Original Soundtrack)", "trackCensoredName": "Killer Queen (2011 Remaster)", "artistViewUrl": "https://music.apple.com/us/artist/queen/3296287?uo=4", "collectionViewUrl": "https://music.apple.com/us/album/killer-queen-2011-remaster/1434899831?i=1434899925&uo=4", "trackViewUrl": "https://music.apple.com/us/album/killer-queen-2011-remaster/1434899831?i=1434899925&uo=4", "previewUrl": "https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview122/v4/e3/06/0d/e3060d43-122a-06f1-0727-046d2fd3d00c/mzaf_10838572092136278634.plus.aac.p.m4a", "artworkUrl30": "https://is1-ssl.mzstatic.com/image/thumb/Music124/v4/ef/54/0b/ef540ba4-bbe7-0809-aa55-97ce32e0e13d/18UMGIM55763.rgb.jpg/30x30bb.jpg", "artworkUrl60": "https://is1-ssl.mzstatic.com/image/thumb/Music124/v4/ef/54/0b/ef540ba4-bbe7-0809-aa55-97ce32e0e13d/18UMGIM55763.rgb.jpg/60x60bb.jpg", "artworkUrl100": "https://is1-ssl.mzstatic.com/image/thumb/Music124/v4/ef/54/0b/ef540ba4-bbe7-0809-aa55-97ce32e0e13d/18UMGIM55763.rgb.jpg/100x100bb.jpg", "collectionPrice": 11.99, "trackPrice": 1.29, "releaseDate": "1974-10-11T12:00:00Z", "collectionExplicitness": "notExplicit", "trackExplicitness": "notExplicit", "discCount": 1, "discNumber": 1, "trackCount": 21, "trackNumber": 5, "trackTimeMillis": 179356, "country": "USA", "currency": "USD", "primaryGenreName": "Rock", "isStreamable": true }, { "wrapperType": "track", "kind": "song", "artistId": 3296287, "collectionId": 1434899831, "trackId": 1434899929, "artistName": "Queen", "collectionName": "Bohemian Rhapsody (The Original Soundtrack)", "trackName": "Bohemian Rhapsody", "collectionCensoredName": "Bohemian Rhapsody (The Original Soundtrack)", "trackCensoredName": "Bohemian Rhapsody (2011 Remaster)", "artistViewUrl": "https://music.apple.com/us/artist/queen/3296287?uo=4", "collectionViewUrl": "https://music.apple.com/us/album/bohemian-rhapsody-2011-remaster/1434899831?i=1434899929&uo=4", "trackViewUrl": "https://music.apple.com/us/album/bohemian-rhapsody-2011-remaster/1434899831?i=1434899929&uo=4", "previewUrl": "https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview122/v4/f6/46/00/f6460056-3685-6c72-f440-dde90e2f52a8/mzaf_7470643542683708752.plus.aac.p.m4a", "artworkUrl30": "https://is1-ssl.mzstatic.com/image/thumb/Music124/v4/ef/54/0b/ef540ba4-bbe7-0809-aa55-97ce32e0e13d/18UMGIM55763.rgb.jpg/30x30bb.jpg", "artworkUrl60": "https://is1-ssl.mzstatic.com/image/thumb/Music124/v4/ef/54/0b/ef540ba4-bbe7-0809-aa55-97ce32e0e13d/18UMGIM55763.rgb.jpg/60x60bb.jpg", "artworkUrl100": "https://is1-ssl.mzstatic.com/image/thumb/Music124/v4/ef/54/0b/ef540ba4-bbe7-0809-aa55-97ce32e0e13d/18UMGIM55763.rgb.jpg/100x100bb.jpg", "collectionPrice": 11.99, "trackPrice": 1.29, "releaseDate": "1975-10-31T12:00:00Z", "collectionExplicitness": "notExplicit", "trackExplicitness": "notExplicit", "discCount": 1, "discNumber": 1, "trackCount": 21, "trackNumber": 7, "trackTimeMillis": 354947, "country": "USA", "currency": "USD", "primaryGenreName": "Rock", "isStreamable": true } ] } ``` ### Lookup Song by ID ```ts // npm import { lookupItunes } from "node-itunes-search"; // jsr import { lookupItunes } from "@nullbitme/search-itunes"; const results = await lookupItunes({ id: "1440660665", // This can optionally be an array of known string ids }); console.log(results); ``` ```json { "resultCount": 1, "results": [ { "wrapperType": "track", "kind": "song", "artistId": 857919, "collectionId": 1440660649, "trackId": 1440660665, "artistName": "Queens of the Stone Age", "collectionName": "Era Vulgaris", "trackName": "River In the Road", "collectionCensoredName": "Era Vulgaris", "trackCensoredName": "River In the Road", "artistViewUrl": "https://music.apple.com/us/artist/queens-of-the-stone-age/857919?uo=4", "collectionViewUrl": "https://music.apple.com/us/album/river-in-the-road/1440660649?i=1440660665&uo=4", "trackViewUrl": "https://music.apple.com/us/album/river-in-the-road/1440660649?i=1440660665&uo=4", "previewUrl": "https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview125/v4/fe/d4/ce/fed4ce08-e3b7-70a5-f532-829aa76ed8be/mzaf_620311569877156662.plus.aac.p.m4a", "artworkUrl30": "https://is1-ssl.mzstatic.com/image/thumb/Music124/v4/ef/d4/60/efd46037-fa6d-7fe3-5ff6-03a48e011744/00602517401488.rgb.jpg/30x30bb.jpg", "artworkUrl60": "https://is1-ssl.mzstatic.com/image/thumb/Music124/v4/ef/d4/60/efd46037-fa6d-7fe3-5ff6-03a48e011744/00602517401488.rgb.jpg/60x60bb.jpg", "artworkUrl100": "https://is1-ssl.mzstatic.com/image/thumb/Music124/v4/ef/d4/60/efd46037-fa6d-7fe3-5ff6-03a48e011744/00602517401488.rgb.jpg/100x100bb.jpg", "collectionPrice": 10.99, "trackPrice": 1.29, "releaseDate": "2007-01-01T12:00:00Z", "collectionExplicitness": "notExplicit", "trackExplicitness": "notExplicit", "discCount": 1, "discNumber": 1, "trackCount": 12, "trackNumber": 10, "trackTimeMillis": 199080, "country": "USA", "currency": "USD", "primaryGenreName": "Rock", "isStreamable": true } ] } ``` ## Contributing Feel free to make an issue or pull request and i'll try to review it as soon as I can. --- _Source: https://npm.io/package/node-itunes-search · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._