Using the Itunes API with Apps Script

The Itunes API is very nice. You can find details on it at ITunes API

I thought I may as well add an Apps Script wrapper library to it, since it can provide a wealth of test data to play around with, and it may be useful to some. 

Set up

The API is open and public, so no need for API keys or anything. 

Getting a instance of ITunesAPI


You'll need the cITunesAPI library (or you can get in from github)

1FeGYcGKYcUQf6X1ips7yOJPKx7k7H9APqcpp5eDeJngJcbK-bLiIRw-F


Then you can do this 

var itunes = new cITunesAPI.ITunesAPI();

I've implemented two kinds of retrieval methods
  • Lookup - you can get specific itunes entries given some of the various itunes IDS
  • Search - you can do a text search to return entries

Examples

The are many parameters, documented in the itunes api page, so I'll show a selection of examples here to see how you can invoke them with the Apps Script library. The format of the results object is the same as I use for many of the libraries, and looks like this
      {
          response: - the string response received from the API - will be populated if there was an error in parsing it.
          data: - the parsed data as an object
          success: - whether it worked
          err: - if it failed, then the error object
        }; 

so check result.success, and if all is well you can use result.data.

// lookup by itunes id
  var result = itunes.lookupById(284910350).data;
  
  // look up by itunes artistid
  var result = itunes.lookupById(909253).data;
  
All of these lookups can take multiple ids. Just specifify them in a list  
  // look up by amgartist id.. can do multiple
  var result = itunes.lookupByAmgArtistId([468749,5723]).data;

Any API parameters can be added to an array  as the second argument to the lookup method. Dont encode them - the library will take care of that.
  // add extra parameters
  var result = itunes.lookupById(909253,["entity=album"]);
  
  // lookup by upc
  var result  = itunes.lookupByUpc(720642462928).data;
  
  // look up the tracks on an album
  var result = itunes.lookupByUpc(720642462928,["entity=song"]).data;
  
  // lookup by a list of amgalbumids
  var result = itunes.lookupByAmgAlbumId([15191,15197]).data;
  
  // look up by video id
  var result = itunes.lookupByAmgVideoId([17120]).data;
  
  // a book by its isbn
  var result = itunes.lookupByIsbn(9780316069359).data;
  
The searchTerm method takes a simple text search, in addition to any of the API optional parameters
  // search for specific entities with a limit and sort
 var result = itunes.searchTerm("beyonce",["limit=5","entity=musicVideo","sort=recent"])).data
  
The default limit on searches is 50, and the maximum is 200. There is no way of pagination if you need to get back more
  // search
  var sean = itunes.searchTerm("sean connery",["limit=200"]).data;

  
Here's an example of the results
"data": {
"resultCount": 50,
"results": [{
"wrapperType": "track",
"kind": "feature-movie",
"collectionId": 779189903,
"trackId": 211292501,
"artistName": "John McTiernan",
"collectionName": "The Jack Ryan Collection",
"trackName": "The Hunt for Red October",
"collectionCensoredName": "The Jack Ryan Collection",
"trackCensoredName": "The Hunt for Red October",
"collectionArtistId": 1008915738,
"collectionArtistViewUrl": "https://itunes.apple.com/us/artist/paramount-home-entertainment/id1008915738?uo=4",
"collectionViewUrl": "https://itunes.apple.com/us/movie/the-hunt-for-red-october/id211292501?uo=4",
"trackViewUrl": "https://itunes.apple.com/us/movie/the-hunt-for-red-october/id211292501?uo=4",
"previewUrl": "http://a880.phobos.apple.com/us/r1000/011/Video/40/b7/a5/mzm.itluknbi..640x254.h264lc.D2.p.m4v",
"artworkUrl30": "http://is5.mzstatic.com/image/thumb/Video49/v4/45/95/56/45955680-f8f6-bff9-3081-30135e602bf9/source/30x30bb.jpg",
"artworkUrl60": "http://is5.mzstatic.com/image/thumb/Video49/v4/45/95/56/45955680-f8f6-bff9-3081-30135e602bf9/source/60x60bb.jpg",
"artworkUrl100": "http://is5.mzstatic.com/image/thumb/Video49/v4/45/95/56/45955680-f8f6-bff9-3081-30135e602bf9/source/100x100bb.jpg",
"collectionPrice": 24.99,
"trackPrice": 9.99,
"trackRentalPrice": 2.99,
"collectionHdPrice": 29.99,
"trackHdPrice": 14.99,
"trackHdRentalPrice": 3.99,
"releaseDate": "1990-03-02T08:00:00Z",
"collectionExplicitness": "notExplicit",
"trackExplicitness": "notExplicit",
"discCount": 1,
"discNumber": 1,
"trackCount": 4,
"trackNumber": 1,
"trackTimeMillis": 8129627,
"country": "USA",
"currency": "USD",
"primaryGenreName": "Thriller",
"contentAdvisoryRating": "PG",
"longDescription": "Based on Tom Clancy's bestseller, directed by John McTiernan (Die Hard) and starring Sean Connery and Alec Baldwin, The Hunt For Red October seethes with high-tech excitement and sweats with the tension of men who hold Doomsday in their hands. A new technologically-superior Soviet nuclear sub, the Red October, is heading for the U.S. coast under the command of Captain Marko Ramius (Connery). The American government thinks Ramius is planning to attack. A lone CIA analyst (Baldwin) has a different idea: he thinks Ramius is planning to defect, but he has only a few hours to find him and prove it - because the entire Russion naval and air commands are trying to find him, too. The hunt is on!"
}

If you want to dump that to a sheet, you may not want all of it. Here's a handy pattern to selectively write out some fields  
// dump to a sheet
  var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName('sean connery');
  sheet.clearContents();
  
  // there are loads of fields, but i'll just take these for demo.
  var fields = ["kind","trackName","artistName","trackName",
                "trackViewUrl","trackPrice",
                "releaseDate",
                "primaryGenreName","trackId"];
  
  var values = [fields].concat(sean.results.map (function (d) {
    return fields.map (function (f) {
      return d[f];
    });
  }));
                               
  // write that out
  sheet.getRange (1,1,values.length,fields.length).setValues(values);

  

Which gives you something like this.



and that's all folks..

For more like this, see Google Apps Scripts snippets. Why not join our forumfollow the blog or follow me on twitter to ensure you get updates when they are available. 

You want to learn Google Apps Script?

Learning Apps Script, (and transitioning from VBA) are covered comprehensively in my my book, Going Gas - from VBA to Apps script, available All formats are available now from O'Reilly,Amazon and all good bookshops. You can also read a preview on O'Reilly

If you prefer Video style learning I also have two courses available. also published by O'Reilly.
Google Apps Script for Developers and Google Apps Script for Beginners.






Comments