ituner

a client library for searching songs on the iTunes store and retrieve the nearest match

Usage no npm install needed!

<script type="module">
  import ituner from 'https://cdn.skypack.dev/ituner';
</script>

README

iTuner

Simple iTunes search library that provides song search and best match retrieval from the Apple iTunes API

Install

npm install ituner

Usage:

In your code, require the ituner module as follows.

var ituner = require('ituner');

var client = ituner({
  allowExplicit : 'Yes',
  searchResultLimit : 10,
  searchUrl : 'http://itunes.apple.com/search',
  timeout : 15000
});

Options:

allowExplicit - Accepts Yes or No and defaults to Yes when not supplied
searchResultLimit - Accepts numeric values, defaults to 10 when not supplied
searchUrl - Accepts a string URL for search, defaults to http://itunes.apple.com/search when not supplied
timeout - Accepts a numeric timeout in milliseconds, defaults 15000 (15 seconds) when not supplied

var ituner = require('ituner');

var client = ituner({
  allowExplicit : 'Yes',
  searchResultLimit : 10,
  searchUrl : 'http://itunes.apple.com/search',
  timeout : 15000
});

Find Best Match

Find the single best match for a search:

var client = (require('ituner')());

client.findBestMatch('beck loser', function (err, result) {
  if (err) {
    console.error(err);
  }

  console.log(result);
});

Which returns the following response:

{ wrapperType: 'track',
  kind: 'song',
  artistId: 312095,
  collectionId: 19820272,
  trackId: 19820274,
  artistName: 'Beck',
  collectionName: 'Mellow Gold',
  trackName: 'Loser',
  collectionCensoredName: 'Mellow Gold',
  trackCensoredName: 'Loser',
  artistViewUrl: 'https://itunes.apple.com/us/artist/beck/id312095?uo=4',
  collectionViewUrl: 'https://itunes.apple.com/us/album/loser/id19820272?i=19820274&uo=4',
  trackViewUrl: 'https://itunes.apple.com/us/album/loser/id19820272?i=19820274&uo=4',
  previewUrl: 'http://a583.phobos.apple.com/us/r1000/085/Music/ae/0b/3c/mzm.cnozdqbr.aac.p.m4a',
  artworkUrl30: 'http://a2.mzstatic.com/us/r30/Features/ee/7b/50/dj.egblsblf.30x30-50.jpg',
  artworkUrl60: 'http://a1.mzstatic.com/us/r30/Features/ee/7b/50/dj.egblsblf.60x60-50.jpg',
  artworkUrl100: 'http://a2.mzstatic.com/us/r30/Features/ee/7b/50/dj.egblsblf.100x100-75.jpg',
  collectionPrice: 7.99,
  trackPrice: 1.29,
  releaseDate: '2004-08-10T07:00:00Z',
  collectionExplicitness: 'explicit',
  trackExplicitness: 'notExplicit',
  discCount: 1,
  discNumber: 1,
  trackCount: 13,
  trackNumber: 1,
  trackTimeMillis: 235000,
  country: 'USA',
  currency: 'USD',
  radioStationUrl: 'https://itunes.apple.com/station/idra.19820274' }

Search

Find all matches for a search:

var client = (require('ituner')());

client.search('beck loser', function (err, result) {
  if (err) {
    console.error(err);
  }

  console.log(result);
});

Which returns the following response:

{ wrapperType: 'track',
  kind: 'song',
  artistId: 312095,
  collectionId: 19820272,
  trackId: 19820274,
  artistName: 'Beck',
  collectionName: 'Mellow Gold',
  trackName: 'Loser',
  collectionCensoredName: 'Mellow Gold',
  trackCensoredName: 'Loser',
  artistViewUrl: 'https://itunes.apple.com/us/artist/beck/id312095?uo=4',
  collectionViewUrl: 'https://itunes.apple.com/us/album/loser/id19820272?i=19820274&uo=4',
  trackViewUrl: 'https://itunes.apple.com/us/album/loser/id19820272?i=19820274&uo=4',
  previewUrl: 'http://a583.phobos.apple.com/us/r1000/085/Music/ae/0b/3c/mzm.cnozdqbr.aac.p.m4a',
  artworkUrl30: 'http://a2.mzstatic.com/us/r30/Features/ee/7b/50/dj.egblsblf.30x30-50.jpg',
  artworkUrl60: 'http://a1.mzstatic.com/us/r30/Features/ee/7b/50/dj.egblsblf.60x60-50.jpg',
  artworkUrl100: 'http://a2.mzstatic.com/us/r30/Features/ee/7b/50/dj.egblsblf.100x100-75.jpg',
  collectionPrice: 7.99,
  trackPrice: 1.29,
  releaseDate: '2004-08-10T07:00:00Z',
  collectionExplicitness: 'explicit',
  trackExplicitness: 'notExplicit',
  discCount: 1,
  discNumber: 1,
  trackCount: 13,
  trackNumber: 1,
  trackTimeMillis: 235000,
  country: 'USA',
  currency: 'USD',
  radioStationUrl: 'https://itunes.apple.com/station/idra.19820274' }
{ resultCount: 10,
  results:
   [ { wrapperType: 'track',
       kind: 'song',
       artistId: 312095,
       collectionId: 19820272,
       trackId: 19820274,
       artistName: 'Beck',
       collectionName: 'Mellow Gold',
       trackName: 'Loser',
       collectionCensoredName: 'Mellow Gold',
       trackCensoredName: 'Loser',
       artistViewUrl: 'https://itunes.apple.com/us/artist/beck/id312095?uo=4',
       collectionViewUrl: 'https://itunes.apple.com/us/album/loser/id19820272?i=19820274&uo=4',
       trackViewUrl: 'https://itunes.apple.com/us/album/loser/id19820272?i=19820274&uo=4',
       previewUrl: 'http://a583.phobos.apple.com/us/r1000/085/Music/ae/0b/3c/mzm.cnozdqbr.aac.p.m4a',
       artworkUrl30: 'http://a2.mzstatic.com/us/r30/Features/ee/7b/50/dj.egblsblf.30x30-50.jpg',
       artworkUrl60: 'http://a1.mzstatic.com/us/r30/Features/ee/7b/50/dj.egblsblf.60x60-50.jpg',
       artworkUrl100: 'http://a2.mzstatic.com/us/r30/Features/ee/7b/50/dj.egblsblf.100x100-75.jpg',
       collectionPrice: 7.99,
       trackPrice: 1.29,
       releaseDate: '2004-08-10T07:00:00Z',
       collectionExplicitness: 'explicit',
       trackExplicitness: 'notExplicit',
       discCount: 1,
       discNumber: 1,
       trackCount: 13,
       trackNumber: 1,
       trackTimeMillis: 235000,
       country: 'USA',
       currency: 'USD',
       radioStationUrl: 'https://itunes.apple.com/station/idra.19820274' },
     { wrapperType: 'track',
       kind: 'song',
       artistId: 312095,
       collectionId: 364279,
       trackId: 364275,
       artistName: 'Beck',
       collectionName: 'Loser - EP',
       trackName: 'Loser',
       collectionCensoredName: 'Loser - EP',
       trackCensoredName: 'Loser',
       artistViewUrl: 'https://itunes.apple.com/us/artist/beck/id312095?uo=4',
       collectionViewUrl: 'https://itunes.apple.com/us/album/loser/id364279?i=364275&uo=4',
       trackViewUrl: 'https://itunes.apple.com/us/album/loser/id364279?i=364275&uo=4',
       previewUrl: 'http://a874.phobos.apple.com/us/r1000/098/Music/75/7c/61/mzm.nzibfkej.aac.p.m4a',
       artworkUrl30: 'http://a2.mzstatic.com/us/r30/Features/c3/2a/c0/dj.ahgolsib.30x30-50.jpg',
       artworkUrl60: 'http://a1.mzstatic.com/us/r30/Features/c3/2a/c0/dj.ahgolsib.60x60-50.jpg',
       artworkUrl100: 'http://a3.mzstatic.com/us/r30/Features/c3/2a/c0/dj.ahgolsib.100x100-75.jpg',
       collectionPrice: 4.99,
       trackPrice: 1.29,
       releaseDate: '1994-01-18T08:00:00Z',
       collectionExplicitness: 'notExplicit',
       trackExplicitness: 'notExplicit',
       discCount: 1,
       discNumber: 1,
       trackCount: 5,
       trackNumber: 1,
       trackTimeMillis: 234975,
       country: 'USA',
       currency: 'USD',
       radioStationUrl: 'https://itunes.apple.com/station/idra.364275' },
     { wrapperType: 'track',
       kind: 'song',
       artistId: 315816847,
       collectionId: 369246323,
       trackId: 369247050,
       artistName: 'Glee Cast',
       collectionName: 'Glee: The Music, Vol. 3 - Showstoppers (Deluxe Edition)',
       trackName: 'Loser (Glee Cast Version)',
       collectionCensoredName: 'Glee: The Music, Vol. 3 - Showstoppers (Deluxe Edition)',
       trackCensoredName: 'Loser (Glee Cast Version)',
       artistViewUrl: 'https://itunes.apple.com/us/artist/glee-cast/id315816847?uo=4',
       collectionViewUrl: 'https://itunes.apple.com/us/album/loser-glee-cast-version/id369246323?i=369247050&uo=4',
       trackViewUrl: 'https://itunes.apple.com/us/album/loser-glee-cast-version/id369246323?i=369247050&uo=4',
       previewUrl: 'http://a1124.phobos.apple.com/us/r1000/070/Music/b3/98/24/mzm.fztiwlyq.aac.p.m4a',
       artworkUrl30: 'http://a2.mzstatic.com/us/r30/Music/78/8a/aa/mzi.elgldove.30x30-50.jpg',
       artworkUrl60: 'http://a1.mzstatic.com/us/r30/Music/78/8a/aa/mzi.elgldove.60x60-50.jpg',
       artworkUrl100: 'http://a2.mzstatic.com/us/r30/Music/78/8a/aa/mzi.elgldove.100x100-75.jpg',
       collectionPrice: 13.99,
       trackPrice: 1.29,
       releaseDate: '2010-05-18T07:00:00Z',
       collectionExplicitness: 'notExplicit',
       trackExplicitness: 'notExplicit',
       discCount: 1,
       discNumber: 1,
       trackCount: 20,
       trackNumber: 16,
       trackTimeMillis: 227659,
       country: 'USA',
       currency: 'USD',
       primaryGenreName: 'Pop',
       radioStationUrl: 'https://itunes.apple.com/station/idra.369247050' },
     { wrapperType: 'track',
       kind: 'song',
       artistId: 312095,
       collectionId: 19820345,
       trackId: 19820347,
       artistName: 'Beck',
       collectionName: 'Mellow Gold',
       trackName: 'Loser',
       collectionCensoredName: 'Mellow Gold',
       trackCensoredName: 'Loser',
       artistViewUrl: 'https://itunes.apple.com/us/artist/beck/id312095?uo=4',
       collectionViewUrl: 'https://itunes.apple.com/us/album/loser/id19820345?i=19820347&uo=4',
       trackViewUrl: 'https://itunes.apple.com/us/album/loser/id19820345?i=19820347&uo=4',
       previewUrl: 'http://a250.phobos.apple.com/us/r1000/105/Music/46/bb/2d/mzm.qdypppej.aac.p.m4a',
       artworkUrl30: 'http://a5.mzstatic.com/us/r30/Features/83/69/79/dj.qnnhporj.30x30-50.jpg',
       artworkUrl60: 'http://a4.mzstatic.com/us/r30/Features/83/69/79/dj.qnnhporj.60x60-50.jpg',
       artworkUrl100: 'http://a1.mzstatic.com/us/r30/Features/83/69/79/dj.qnnhporj.100x100-75.jpg',
       collectionPrice: 9.99,
       trackPrice: 1.29,
       releaseDate: '2004-08-10T07:00:00Z',
       collectionExplicitness: 'cleaned',
       trackExplicitness: 'notExplicit',
       discCount: 1,
       discNumber: 1,
       trackCount: 13,
       trackNumber: 1,
       trackTimeMillis: 235000,
       country: 'USA',
       currency: 'USD',
       radioStationUrl: 'https://itunes.apple.com/station/idra.19820347' },
     { wrapperType: 'track',
       kind: 'song',
       artistId: 312095,
       collectionId: 269606347,
       trackId: 269607766,
       artistName: 'Beck',
       collectionName: 'Lance Armstrong: Run Longer',
       trackName: 'Loser',
       collectionCensoredName: 'Lance Armstrong: Run Longer',
       trackCensoredName: 'Loser',
       collectionArtistId: 36270,
       collectionArtistName: 'Various Artists',
       artistViewUrl: 'https://itunes.apple.com/us/artist/beck/id312095?uo=4',
       collectionViewUrl: 'https://itunes.apple.com/us/album/loser/id269606347?i=269607766&uo=4',
       trackViewUrl: 'https://itunes.apple.com/us/album/loser/id269606347?i=269607766&uo=4',
       previewUrl: 'http://a519.phobos.apple.com/us/r1000/086/Music/bc/fe/6c/mzm.rwxftozk.aac.p.m4a',
       artworkUrl30: 'http://a1.mzstatic.com/us/r30/Features/v4/f7/c8/70/f7c87018-acec-f317-2a98-b7ed362b5451/V4HttpAssetRepositoryClient-ticket.efltxylb.jpg-7966645662810885187.30x30-50.jpg',
       artworkUrl60: 'http://a3.mzstatic.com/us/r30/Features/v4/f7/c8/70/f7c87018-acec-f317-2a98-b7ed362b5451/V4HttpAssetRepositoryClient-ticket.efltxylb.jpg-7966645662810885187.60x60-50.jpg',
       artworkUrl100: 'http://a5.mzstatic.com/us/r30/Features/v4/f7/c8/70/f7c87018-acec-f317-2a98-b7ed362b5451/V4HttpAssetRepositoryClient-ticket.efltxylb.jpg-7966645662810885187.100x100-75.jpg',
       collectionPrice: 13.99,
       trackPrice: 1.29,
       releaseDate: '2007-12-11T08:00:00Z',
       collectionExplicitness: 'notExplicit',
       trackExplicitness: 'notExplicit',
       discCount: 1,
       discNumber: 1,
       trackCount: 14,
       trackNumber: 13,
       trackTimeMillis: 235920,
       country: 'USA',
       currency: 'USD',
       primaryGenreName: 'Alternative',
       radioStationUrl: 'https://itunes.apple.com/station/idra.269607766' },
     { wrapperType: 'track',
       kind: 'song',
       artistId: 312095,
       collectionId: 364279,
       trackId: 364273,
       artistName: 'Beck',
       collectionName: 'Loser - EP',
       trackName: 'Fume',
       collectionCensoredName: 'Loser - EP',
       trackCensoredName: 'Fume',
       artistViewUrl: 'https://itunes.apple.com/us/artist/beck/id312095?uo=4',
       collectionViewUrl: 'https://itunes.apple.com/us/album/fume/id364279?i=364273&uo=4',
       trackViewUrl: 'https://itunes.apple.com/us/album/fume/id364279?i=364273&uo=4',
       previewUrl: 'http://a1388.phobos.apple.com/us/r1000/105/Music/a5/12/8f/mzm.xevlvmcw.aac.p.m4a',
       artworkUrl30: 'http://a2.mzstatic.com/us/r30/Features/c3/2a/c0/dj.ahgolsib.30x30-50.jpg',
       artworkUrl60: 'http://a1.mzstatic.com/us/r30/Features/c3/2a/c0/dj.ahgolsib.60x60-50.jpg',
       artworkUrl100: 'http://a3.mzstatic.com/us/r30/Features/c3/2a/c0/dj.ahgolsib.100x100-75.jpg',
       collectionPrice: 4.99,
       trackPrice: 0.99,
       releaseDate: '1994-01-18T08:00:00Z',
       collectionExplicitness: 'notExplicit',
       trackExplicitness: 'notExplicit',
       discCount: 1,
       discNumber: 1,
       trackCount: 5,
       trackNumber: 5,
       trackTimeMillis: 269182,
       country: 'USA',
       currency: 'USD',
       primaryGenreName: 'Rock',
       radioStationUrl: 'https://itunes.apple.com/station/idra.364273' },
     { wrapperType: 'track',
       kind: 'song',
       artistId: 312095,
       collectionId: 364279,
       trackId: 364266,
       artistName: 'Beck',
       collectionName: 'Loser - EP',
       trackName: 'Alcohol',
       collectionCensoredName: 'Loser - EP',
       trackCensoredName: 'Alcohol',
       artistViewUrl: 'https://itunes.apple.com/us/artist/beck/id312095?uo=4',
       collectionViewUrl: 'https://itunes.apple.com/us/album/alcohol/id364279?i=364266&uo=4',
       trackViewUrl: 'https://itunes.apple.com/us/album/alcohol/id364279?i=364266&uo=4',
       previewUrl: 'http://a633.phobos.apple.com/us/r1000/083/Music/8d/92/54/mzm.ravaqjgk.aac.p.m4a',
       artworkUrl30: 'http://a2.mzstatic.com/us/r30/Features/c3/2a/c0/dj.ahgolsib.30x30-50.jpg',
       artworkUrl60: 'http://a1.mzstatic.com/us/r30/Features/c3/2a/c0/dj.ahgolsib.60x60-50.jpg',
       artworkUrl100: 'http://a3.mzstatic.com/us/r30/Features/c3/2a/c0/dj.ahgolsib.100x100-75.jpg',
       collectionPrice: 4.99,
       trackPrice: 0.99,
       releaseDate: '1994-01-18T08:00:00Z',
       collectionExplicitness: 'notExplicit',
       trackExplicitness: 'notExplicit',
       discCount: 1,
       discNumber: 1,
       trackCount: 5,
       trackNumber: 3,
       trackTimeMillis: 231048,
       country: 'USA',
       currency: 'USD',
       primaryGenreName: 'Rock',
       radioStationUrl: 'https://itunes.apple.com/station/idra.364266' },
     { wrapperType: 'track',
       kind: 'song',
       artistId: 312095,
       collectionId: 364279,
       trackId: 364277,
       artistName: 'Beck',
       collectionName: 'Loser - EP',
       trackName: 'Corvette Bummer',
       collectionCensoredName: 'Loser - EP',
       trackCensoredName: 'Corvette Bummer',
       artistViewUrl: 'https://itunes.apple.com/us/artist/beck/id312095?uo=4',
       collectionViewUrl: 'https://itunes.apple.com/us/album/corvette-bummer/id364279?i=364277&uo=4',
       trackViewUrl: 'https://itunes.apple.com/us/album/corvette-bummer/id364279?i=364277&uo=4',
       previewUrl: 'http://a79.phobos.apple.com/us/r1000/103/Music/a0/f9/02/mzm.nwzndlvq.aac.p.m4a',
       artworkUrl30: 'http://a2.mzstatic.com/us/r30/Features/c3/2a/c0/dj.ahgolsib.30x30-50.jpg',
       artworkUrl60: 'http://a1.mzstatic.com/us/r30/Features/c3/2a/c0/dj.ahgolsib.60x60-50.jpg',
       artworkUrl100: 'http://a3.mzstatic.com/us/r30/Features/c3/2a/c0/dj.ahgolsib.100x100-75.jpg',
       collectionPrice: 4.99,
       trackPrice: 0.99,
       releaseDate: '1994-01-18T08:00:00Z',
       collectionExplicitness: 'notExplicit',
       trackExplicitness: 'notExplicit',
       discCount: 1,
       discNumber: 1,
       trackCount: 5,
       trackNumber: 2,
       trackTimeMillis: 297305,
       country: 'USA',
       currency: 'USD',
       primaryGenreName: 'Rock',
       radioStationUrl: 'https://itunes.apple.com/station/idra.364277' },
     { wrapperType: 'track',
       kind: 'song',
       artistId: 312095,
       collectionId: 364279,
       trackId: 364271,
       artistName: 'Beck',
       collectionName: 'Loser - EP',
       trackName: 'Soul Suckin\' Jerk (Reject Version)',
       collectionCensoredName: 'Loser - EP',
       trackCensoredName: 'Soul Suckin\' Jerk (Reject Version)',
       artistViewUrl: 'https://itunes.apple.com/us/artist/beck/id312095?uo=4',
       collectionViewUrl: 'https://itunes.apple.com/us/album/soul-suckin-jerk-reject-version/id364279?i=364271&uo=4',
       trackViewUrl: 'https://itunes.apple.com/us/album/soul-suckin-jerk-reject-version/id364279?i=364271&uo=4',
       previewUrl: 'http://a1315.phobos.apple.com/us/r1000/103/Music/a7/6f/92/mzm.enfiixwa.aac.p.m4a',
       artworkUrl30: 'http://a2.mzstatic.com/us/r30/Features/c3/2a/c0/dj.ahgolsib.30x30-50.jpg',
       artworkUrl60: 'http://a1.mzstatic.com/us/r30/Features/c3/2a/c0/dj.ahgolsib.60x60-50.jpg',
       artworkUrl100: 'http://a3.mzstatic.com/us/r30/Features/c3/2a/c0/dj.ahgolsib.100x100-75.jpg',
       collectionPrice: 4.99,
       trackPrice: 0.99,
       releaseDate: '1994-01-18T08:00:00Z',
       collectionExplicitness: 'notExplicit',
       trackExplicitness: 'notExplicit',
       discCount: 1,
       discNumber: 1,
       trackCount: 5,
       trackNumber: 4,
       trackTimeMillis: 370141,
       country: 'USA',
       currency: 'USD',
       primaryGenreName: 'Rock',
       radioStationUrl: 'https://itunes.apple.com/station/idra.364271' },
     { wrapperType: 'track',
       kind: 'song',
       artistId: 5413685,
       collectionId: 537819688,
       trackId: 537820140,
       artistName: 'Dr. Lonnie Smith',
       collectionName: 'Boogaloo to Beck',
       trackName: 'Loser',
       collectionCensoredName: 'Boogaloo to Beck',
       trackCensoredName: 'Loser',
       artistViewUrl: 'https://itunes.apple.com/us/artist/dr.-lonnie-smith/id5413685?uo=4',
       collectionViewUrl: 'https://itunes.apple.com/us/album/loser/id537819688?i=537820140&uo=4',
       trackViewUrl: 'https://itunes.apple.com/us/album/loser/id537819688?i=537820140&uo=4',
       previewUrl: 'http://a267.phobos.apple.com/us/r1000/108/Music/23/0d/09/mzi.rjgopikm.aac.p.m4a',
       artworkUrl30: 'http://a5.mzstatic.com/us/r30/Music/v4/28/a6/86/28a68663-dd12-9a65-b041-e98d891dfaeb/cover.30x30-50.jpg',
       artworkUrl60: 'http://a2.mzstatic.com/us/r30/Music/v4/28/a6/86/28a68663-dd12-9a65-b041-e98d891dfaeb/cover.60x60-50.jpg',
       artworkUrl100: 'http://a2.mzstatic.com/us/r30/Music/v4/28/a6/86/28a68663-dd12-9a65-b041-e98d891dfaeb/cover.100x100-75.jpg',
       collectionPrice: 10.89,
       trackPrice: 0.99,
       releaseDate: '2003-05-20T07:00:00Z',
       collectionExplicitness: 'notExplicit',
       trackExplicitness: 'notExplicit',
       discCount: 1,
       discNumber: 1,
       trackCount: 11,
       trackNumber: 7,
       trackTimeMillis: 196013,
       country: 'USA',
       currency: 'USD',
       primaryGenreName: 'Jazz',
       radioStationUrl: 'https://itunes.apple.com/station/idra.537820140' } ] }