Jamming With the Music APIs

As a front-end engineer for Yahoo! Music, I've always thought it would great if the web services we use to create the Y! Music pages were available to developers outside of Yahoo!, and, as of today, due to the herculean labors of our web services team, they are!

I've created a bare-bones PHP application, for browsing and playing music videos, so you can see some of the cool things you can do with the Music API. You can download the PHP source code here, and preview it here. You'll probably want to look at the Music API documentation while perusing the source code.

There are a large number of API calls available in the Music API. I find that there is a relatively small handful that I use over and over again, so I'm going to point out those workhorse calls.

## Search for Artists

Most of the music API calls rely on a set of unique numeric IDs to obtain information. There are artist IDs, which correspond to bands and solo artists, track IDs, video IDs, and so on.

My apps often start by using an artist ID to obtain a list of videos or tracks for a particular artist.

You can use the Search for Artists call to obtain the artist ID for a particular artist, if you know the name.

Here's a sample artist search.

Note that the search will return multiple results, but you will often only be interested in the first result, which is the most relevant. You can limit the number of results to one, by adding a count=1 parameter, like so. This will reduce bandwidth and speed up the API call.

## Get Artist Info

If you already know the artist ID, it's faster to retrieve artist information using the Artist by ID call.

Here are a few samples to get your started:

289282 Britney Spears
256352 Madonna
312054 Daft Punk

There are some options to this call you should be aware of. You can add tracks or videos to the results returned using the "response" option, like so:

Note that if you must perform an artist search, all these items can also be returned as part of the search results, also using the response option.
You can combine response options in a single call by separating them with a comma. Don't go overboard with these additional response items if you don't need them - they will definitely slow the response time.

## Get Video Thumbnail Images

For every video that is listed, you can get a thumbnail, using a URL like this:


Where VID is the video id, and SIZE is the desired width of the image, here's a working sample:


If you leave off the size parameter, you get the original size, which is typically 385x231. Check out the additional image parameters here.

Note that the image URLs do NOT require an appid parameter, like the regular API calls (and in fact, will fail if one is provided). Also,
image retrieval does not contribute to the API quota (more on this below).

## Play Videos

Not only can you display video stills, you can also embed a Flash player for the actual music videos. Sample code for this is
provided in the documentation, as well as in my sample app, which implements the player markup in PHP.

## Browse Similar Artists

My personal favorite of the API calls is the one that provides a list of similar artists to a given artist. This call provides a
great browsing mechanism, as most of the artists in the catalog are connected through a vast tree of similarity.

Here's a sample listing of the artists similar to Daft Punk.

A fun variant of the "Six Degrees of Kevin Bacon" game is to try to find the connections from Kevin Bacon's Band to a more mainstream artist, such as Madonna.

Here's a Flash-based similarities browser, using this API that you can use to play this game.

## Tips

Here are some final tips to help you get the most out of the Y! Music APIs.

1. Authentication is only needed for a small part of the API, involving user ratings. If you simply wish to navigate through
the artist discographies and play videos, you don't need full authentication, which makes using the API much simpler -- you only need a valid application ID. In the sample
PHP code provided above, I'm using only unauthenticated calls.

2. The API has a rate limit of 5K queries per day per end-user IP address. This only applies to the calls that return data, not the image URLs. A good way to work around this is to locally cache results for 24 hours - you'll find for most apps, the number of unique queries you need to make is well under 5K. In the sample PHP code provided above, I've implemented such a caching system. This also greatly improves the performance of the app, since cached API results are delivered much faster.

3. I prefer using these APIs with server-side scripts, such as PHP, rather than client-side scripts, such as Javascript & AJAX.
This is because I can get better performance by implementing server-side caching (as described in tip 2). If you want to set up
an AJAX app, I would suggest setting up a proxy for these services--to implement caching.

Jim Bumgardner
Yahoo! Music Nerd