Two different types of searches are possible using the Search API. These are done using a set of parameters to do a search or using an ID to do a look up.
You can pass in different parameters to define a search; such as type of entity you are looking for, the media type, related attributes, related terms, etc. A full list of these parameters can be found inside the Search API documentation. These types of searches are done using the wsSearch service. The base URL for a wsSearch looks like this: http://ax.itunes.apple.com/WebObjects/MZStoreServices.woa/wa/wsSearch?
If you already have an iTunes Adam ID, an AMG ID or a UPC you can also use the Search API to find relevant information from iTunes for item you are looking up. This is done by adding amgArtistId, upc, id, amgAlbumId, etc. to the base of a wsLookup URL: http://ax.itunes.apple.com/WebObjects/MZStoreServices.woa/wa/wsLookup?
While the results that are given will vary depending on what type of content is being returned there are a few important things to look out for. Here is a breakdown of the results based off of a search for a specific song. – The most important is the URL into the iTunes store for the relevant artist (artistViewUrl), collection (album [collectionViewUrl]) and track (song [trackViewUrl]). It is important to note that these are raw iTunes URLs and must be properly affiliate encoded before they will generate a commission. – Also of interest is the artist (artistName), collection (collectionName) and track names (trackName), as recognized in the iTunes Store. – The pricing associated with the collection (collectionPrice) and track (trackPrice) is also available in the data as well as the relevant currency (currency). – The genre (primaryGenreName) is also identified in the Search API results as well as relevant cover art in two different sizes (artworkUrl60 and artworkUrl100). – Finally, 30 second sound samples are available to use for songs (trackViewUrl) but must only be played in on US based websites and when a buy on iTunes button is associated with them.
Here are a few tips to help you get acquainted to the Search API. – Reading through unformatted JSON results can be a challenge. Use a formatter to help.
– The default country is US. If you are looking up IDs for non-US items make sure and include the “country=” and the ISO 2 digit code in the URL. – Adam Ids are easily found as the last set of numbers on a standard iTunes link and used with the wsLookup can provide a loot of good information. – To find all the parameters that are acceptable to be included in the Search API query you can cause the query to “dump.” You do this by sending in an improperly built query. Try this: http://ax.itunes.apple.com/WebObjects/MZStoreServices.woa/wa/wsSearch?term=jack+johnson&country=UK (The ISO two code for the UK is actually ‘GB’).
While the Search API is relatively easy to use and get started with it is important to note it’s limitations. Because it is web based results can sometimes be slow. In order to deal with this we recommend building a caching system to reduce the number of calls you make to the service or to look into building your own server side service using our Enterprise Partner Feed.
If you find you are a heavy user of the iTunes Link Maker tool or are looking for a way to start automating some of your affiliate link generation I highly recommend you first take at look at the Search API documentation and then jump right in!