{"id":27127847,"url":"https://github.com/jacob-shuman/node-itunes-search","last_synced_at":"2025-07-11T12:03:48.143Z","repository":{"id":33201815,"uuid":"154770309","full_name":"jacob-shuman/node-itunes-search","owner":"jacob-shuman","description":"A wrapper around the iTunes Search API","archived":false,"fork":false,"pushed_at":"2024-09-26T17:32:08.000Z","size":302,"stargazers_count":26,"open_issues_count":0,"forks_count":7,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-11T18:18:12.583Z","etag":null,"topics":["api","itunes","jsr","music","nodejs","nodejs-wrapper","npm","pnpm","typescript","wrapper"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jacob-shuman.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-10-26T03:11:04.000Z","updated_at":"2025-05-30T20:54:03.000Z","dependencies_parsed_at":"2024-06-19T01:46:13.328Z","dependency_job_id":null,"html_url":"https://github.com/jacob-shuman/node-itunes-search","commit_stats":{"total_commits":88,"total_committers":5,"mean_commits":17.6,"dds":"0.20454545454545459","last_synced_commit":"b061388fe40d1e86df4fbc75eb45b9c063d0c1b8"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/jacob-shuman/node-itunes-search","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacob-shuman%2Fnode-itunes-search","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacob-shuman%2Fnode-itunes-search/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacob-shuman%2Fnode-itunes-search/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacob-shuman%2Fnode-itunes-search/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jacob-shuman","download_url":"https://codeload.github.com/jacob-shuman/node-itunes-search/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacob-shuman%2Fnode-itunes-search/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264803573,"owners_count":23666508,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","itunes","jsr","music","nodejs","nodejs-wrapper","npm","pnpm","typescript","wrapper"],"created_at":"2025-04-07T17:58:05.198Z","updated_at":"2025-07-11T12:03:47.858Z","avatar_url":"https://github.com/jacob-shuman.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `node-itunes-search`\n\n\u003e 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)\n\u003e\n\u003e _\"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.\"_\n\n## Installation\n\n\u003ca href=\"https://www.npmjs.com/package/node-itunes-search\"\u003e\n\t\u003cpicture\u003e\n\t\t\u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://img.shields.io/badge/npm-node--itunes--search-cb3837?style=for-the-badge\u0026logo=npm\u0026labelColor=202020\u0026logoColor=cb3837\" /\u003e\n\t\t\u003cimg alt=\"npm badge\" src=\"https://img.shields.io/badge/npm-node--itunes--search-cb3837?style=for-the-badge\u0026logo=npm\u0026labelColor=f0f0f0\u0026logoColor=cb3837\" /\u003e\n\t\u003c/picture\u003e\n\u003c/a\u003e\n\n```bash\nnpm install node-itunes-search\n```\n\n\u003ca href=\"https://jsr.io/@nullbitme/search-itunes\"\u003e\n\t\u003cpicture\u003e\n\t\t\u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://img.shields.io/badge/jsr-@nullbitme/search--itunes-f3e050?style=for-the-badge\u0026logo=jsr\u0026labelColor=202020\u0026logoColor=f3e050\" /\u003e\n\t\t\u003cimg alt=\"jsr badge\" src=\"https://img.shields.io/badge/jsr-@nullbitme/search--itunes-f3e050?style=for-the-badge\u0026logo=jsr\u0026labelColor=f0f0f0\u0026logoColor=163242\" /\u003e\n\t\u003c/picture\u003e\n\u003c/a\u003e\n\n```bash\nnpx jsr add @nullbitme/search-itunes\n```\n\n## Usage\n\nThis 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:\n\n```ts\ninterface ItunesResults {\n  resultCount: number;\n\n  // Results of search/lookup\n  results: (ItunesResult \u0026 { [key: string]: unknown })[];\n}\n\ninterface ItunesResults {\n  wrapperType?: ItunesWrapperType;\n  kind?: ItunesKind;\n  artistId?: number;\n  collectionId?: number;\n  trackId?: number;\n  artistName?: string;\n  collectionName?: string;\n  trackName?: string;\n  collectionCensoredName?: string;\n  trackCensoredName?: string;\n  collectionArtistId?: string;\n  collectionArtistViewUrl?: string;\n  artistViewUrl?: string;\n  collectionViewUrl?: string;\n  trackViewUrl?: string;\n  previewUrl?: string;\n  artworkUrl30?: string;\n  artworkUrl60?: string;\n  artworkUrl100?: string;\n  trackRentalPrice?: number;\n  trackHdRentalPrice?: number;\n  collectionPrice?: number;\n  trackPrice?: number;\n  releaseDate?: string;\n  collectionExplicitness?: ItunesExplicitness;\n  trackExplicitness?: ItunesExplicitness;\n  discCount?: number;\n  discNumber?: number;\n  trackCount?: number;\n  trackNumber?: number;\n  trackTimeMillis?: number;\n  country?: string;\n  currency?: string;\n  primaryGenreName?: string;\n  contentAdvisoryRating?: string;\n  shortDescription?: string;\n  longDescription?: string;\n  isStreamable?: boolean;\n  hasITunesExtras?: boolean;\n}\n```\n\nThis 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.\n\n### Search\n\n[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)\n\n```ts\nasync function searchItunes(\n  options: ItunesSearchOptions\n): Promise\u003cItunesResults\u003e;\n```\n\n### Lookup\n\n\u003c!-- TODO: some description --\u003e\n\n[_\"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)\n\n```ts\nasync function lookupItunes(\n  options: ItunesLookupOptions\n): Promise\u003cItunesResults\u003e;\n```\n\n## Examples\n\n### Song Search\n\n```ts\n// npm\nimport { searchItunes } from \"node-itunes-search\";\n// jsr\nimport { searchItunes } from \"@nullbitme/search-itunes\";\n\nconst results = await searchItunes({\n  // Search Query\n  term: \"Queen Bohemian Rhapsody\",\n\n  // Setting max number of results to 2\n  limit: \"2\",\n});\n\nconsole.log(results);\n```\n\n```json\n{\n  \"resultCount\": 2,\n  \"results\": [\n    {\n      \"wrapperType\": \"track\",\n      \"kind\": \"song\",\n      \"artistId\": 3296287,\n      \"collectionId\": 1434899831,\n      \"trackId\": 1434899925,\n      \"artistName\": \"Queen\",\n      \"collectionName\": \"Bohemian Rhapsody (The Original Soundtrack)\",\n      \"trackName\": \"Killer Queen\",\n      \"collectionCensoredName\": \"Bohemian Rhapsody (The Original Soundtrack)\",\n      \"trackCensoredName\": \"Killer Queen (2011 Remaster)\",\n      \"artistViewUrl\": \"https://music.apple.com/us/artist/queen/3296287?uo=4\",\n      \"collectionViewUrl\": \"https://music.apple.com/us/album/killer-queen-2011-remaster/1434899831?i=1434899925\u0026uo=4\",\n      \"trackViewUrl\": \"https://music.apple.com/us/album/killer-queen-2011-remaster/1434899831?i=1434899925\u0026uo=4\",\n      \"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\",\n      \"artworkUrl30\": \"https://is1-ssl.mzstatic.com/image/thumb/Music124/v4/ef/54/0b/ef540ba4-bbe7-0809-aa55-97ce32e0e13d/18UMGIM55763.rgb.jpg/30x30bb.jpg\",\n      \"artworkUrl60\": \"https://is1-ssl.mzstatic.com/image/thumb/Music124/v4/ef/54/0b/ef540ba4-bbe7-0809-aa55-97ce32e0e13d/18UMGIM55763.rgb.jpg/60x60bb.jpg\",\n      \"artworkUrl100\": \"https://is1-ssl.mzstatic.com/image/thumb/Music124/v4/ef/54/0b/ef540ba4-bbe7-0809-aa55-97ce32e0e13d/18UMGIM55763.rgb.jpg/100x100bb.jpg\",\n      \"collectionPrice\": 11.99,\n      \"trackPrice\": 1.29,\n      \"releaseDate\": \"1974-10-11T12:00:00Z\",\n      \"collectionExplicitness\": \"notExplicit\",\n      \"trackExplicitness\": \"notExplicit\",\n      \"discCount\": 1,\n      \"discNumber\": 1,\n      \"trackCount\": 21,\n      \"trackNumber\": 5,\n      \"trackTimeMillis\": 179356,\n      \"country\": \"USA\",\n      \"currency\": \"USD\",\n      \"primaryGenreName\": \"Rock\",\n      \"isStreamable\": true\n    },\n    {\n      \"wrapperType\": \"track\",\n      \"kind\": \"song\",\n      \"artistId\": 3296287,\n      \"collectionId\": 1434899831,\n      \"trackId\": 1434899929,\n      \"artistName\": \"Queen\",\n      \"collectionName\": \"Bohemian Rhapsody (The Original Soundtrack)\",\n      \"trackName\": \"Bohemian Rhapsody\",\n      \"collectionCensoredName\": \"Bohemian Rhapsody (The Original Soundtrack)\",\n      \"trackCensoredName\": \"Bohemian Rhapsody (2011 Remaster)\",\n      \"artistViewUrl\": \"https://music.apple.com/us/artist/queen/3296287?uo=4\",\n      \"collectionViewUrl\": \"https://music.apple.com/us/album/bohemian-rhapsody-2011-remaster/1434899831?i=1434899929\u0026uo=4\",\n      \"trackViewUrl\": \"https://music.apple.com/us/album/bohemian-rhapsody-2011-remaster/1434899831?i=1434899929\u0026uo=4\",\n      \"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\",\n      \"artworkUrl30\": \"https://is1-ssl.mzstatic.com/image/thumb/Music124/v4/ef/54/0b/ef540ba4-bbe7-0809-aa55-97ce32e0e13d/18UMGIM55763.rgb.jpg/30x30bb.jpg\",\n      \"artworkUrl60\": \"https://is1-ssl.mzstatic.com/image/thumb/Music124/v4/ef/54/0b/ef540ba4-bbe7-0809-aa55-97ce32e0e13d/18UMGIM55763.rgb.jpg/60x60bb.jpg\",\n      \"artworkUrl100\": \"https://is1-ssl.mzstatic.com/image/thumb/Music124/v4/ef/54/0b/ef540ba4-bbe7-0809-aa55-97ce32e0e13d/18UMGIM55763.rgb.jpg/100x100bb.jpg\",\n      \"collectionPrice\": 11.99,\n      \"trackPrice\": 1.29,\n      \"releaseDate\": \"1975-10-31T12:00:00Z\",\n      \"collectionExplicitness\": \"notExplicit\",\n      \"trackExplicitness\": \"notExplicit\",\n      \"discCount\": 1,\n      \"discNumber\": 1,\n      \"trackCount\": 21,\n      \"trackNumber\": 7,\n      \"trackTimeMillis\": 354947,\n      \"country\": \"USA\",\n      \"currency\": \"USD\",\n      \"primaryGenreName\": \"Rock\",\n      \"isStreamable\": true\n    }\n  ]\n}\n```\n\n### Lookup Song by ID\n\n```ts\n// npm\nimport { lookupItunes } from \"node-itunes-search\";\n// jsr\nimport { lookupItunes } from \"@nullbitme/search-itunes\";\n\nconst results = await lookupItunes({\n  id: \"1440660665\", // This can optionally be an array of known string ids\n});\n\nconsole.log(results);\n```\n\n```json\n{\n  \"resultCount\": 1,\n  \"results\": [\n    {\n      \"wrapperType\": \"track\",\n      \"kind\": \"song\",\n      \"artistId\": 857919,\n      \"collectionId\": 1440660649,\n      \"trackId\": 1440660665,\n      \"artistName\": \"Queens of the Stone Age\",\n      \"collectionName\": \"Era Vulgaris\",\n      \"trackName\": \"River In the Road\",\n      \"collectionCensoredName\": \"Era Vulgaris\",\n      \"trackCensoredName\": \"River In the Road\",\n      \"artistViewUrl\": \"https://music.apple.com/us/artist/queens-of-the-stone-age/857919?uo=4\",\n      \"collectionViewUrl\": \"https://music.apple.com/us/album/river-in-the-road/1440660649?i=1440660665\u0026uo=4\",\n      \"trackViewUrl\": \"https://music.apple.com/us/album/river-in-the-road/1440660649?i=1440660665\u0026uo=4\",\n      \"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\",\n      \"artworkUrl30\": \"https://is1-ssl.mzstatic.com/image/thumb/Music124/v4/ef/d4/60/efd46037-fa6d-7fe3-5ff6-03a48e011744/00602517401488.rgb.jpg/30x30bb.jpg\",\n      \"artworkUrl60\": \"https://is1-ssl.mzstatic.com/image/thumb/Music124/v4/ef/d4/60/efd46037-fa6d-7fe3-5ff6-03a48e011744/00602517401488.rgb.jpg/60x60bb.jpg\",\n      \"artworkUrl100\": \"https://is1-ssl.mzstatic.com/image/thumb/Music124/v4/ef/d4/60/efd46037-fa6d-7fe3-5ff6-03a48e011744/00602517401488.rgb.jpg/100x100bb.jpg\",\n      \"collectionPrice\": 10.99,\n      \"trackPrice\": 1.29,\n      \"releaseDate\": \"2007-01-01T12:00:00Z\",\n      \"collectionExplicitness\": \"notExplicit\",\n      \"trackExplicitness\": \"notExplicit\",\n      \"discCount\": 1,\n      \"discNumber\": 1,\n      \"trackCount\": 12,\n      \"trackNumber\": 10,\n      \"trackTimeMillis\": 199080,\n      \"country\": \"USA\",\n      \"currency\": \"USD\",\n      \"primaryGenreName\": \"Rock\",\n      \"isStreamable\": true\n    }\n  ]\n}\n```\n\n## Contributing\n\nFeel free to make an issue or pull request and i'll try to review it as soon as I can.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjacob-shuman%2Fnode-itunes-search","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjacob-shuman%2Fnode-itunes-search","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjacob-shuman%2Fnode-itunes-search/lists"}