Many web developers add streaming audio to websites using web services from one of the well-known streaming web players (AKA Internet radio), such as Spotify, Pandora, or Last.fm. Those who want to access the famous Pandora app will be disappointed, however. A bit of searching the web showed that Pandora once offered an open source API, but for whatever reason, deprecated it in 2012.
However, Last.fm offers a REST API that lets web developers access the functionality of its Scrobbler application. What's Scrobbler?
Scrobbler is the Last.fm client application, with which users can play Last.fm radio stations. It automatically fills users' libraries and updates them with what they've been listening to on their computers. Users can also rate music by "loving" and "banning" tracks, assemble playlists, and apply tags to tracks and albums.
What it does
The Last.fm REST API lets web developers use the same functionality in their own web or mobile applications, streaming music from Last.fm and using Last.fm data. The API goes a few steps further, offering tools for gathering statistics and accessing data by various collections (by group, by genre, by artist, etc).
It provides methods that let you operate on the following objects (which Last.fm calls "packages"):
- Album - Access data for an album
- Artist - Access data for an artist
- Auth - Fetch a session key or request token
- Chart - Access chart info for artists or tracks
- Event - Attend or share a live audio event
- Geo - ISO 3166-1 country and metro data for use in the other web services
- Group - Access data for a group
- Library - Maintains tracks/albums in a user's library
- Playlist - Access a user's playlist data
- Radio - Access metadata or streaming audio from a Last.fm radio station
- Tag - Access search tags
- Tasteometer - Access Tasteometer data (a rating score used on Last.fm)
- Track - Access data for a track
- User - Access user data Venue - Access data for a venue for events
How it works
In the Last.fm API, there are two ways to make requests: write operations (using POST) and read operations (using GET).
Write operations
To access a write service, you submit a request as an HTTP POST request to the service endpoint. You send all parameters in the request body. In order to perform write requests, you first have to authenticate a user with the API (not discussed here).
Example: How to "love" a track
(This service is described in the Last.fm REST API documentation at http://www.last.fm/api/show/track.love.)
The track.love method is a write operation and uses HTTP POST. You should send parameters (including the method parameter) in the POST request body to the service endpoint at http://ws.audioscrobbler.com/2.0/.
Parameters
track (Required) : A track name (utf8 encoded)
artist (Required) : An artist name (utf8 encoded)
api_key (Required) : A Last.fm API key.
api_sig (Required) : A Last.fm method signature. See authentication for more information.
sk (Required) : A session key generated by authenticating a user via the authentication protocol.
Request Body
In a write operation, params are sent in the request body of HTTP POST requests as named arguments using a structure as follows:
<methodCall>
<methodName>track.love</methodName>
<params>
<param>
<value>
<struct>
<member>
<name>track</name>
<value>
<string>Ring of Fire</string>
</value>
</member>
<member>
<name>artist</name>
<value>
<string>Johnny Cash</string>
</value>
</member>
<member>
<name>api_key</name>
<value>
<string>AA25BB53CC45DD85EE22FF30GG67HH64</string>
</value>
</member>
<member>
<name>api_sig</name>
<value>
<string>BB89CC55DD80EE11FF41GG07HH18II99</string>
</value>
</member>
<member>
<name>sk</name>
<value>
<string>CC12DD45EE67FF24GG56HH88II36ZZ00</string>
</value>
</member>
</struct>
</value>
</param>
</params>
</methodCall>
Read operations
To access a read service, submit a request as an HTTP GET request to the service endpoint. You send all parameters in the request URI. You don't have to authenticate a user with the API to perform read operations.
Example: How to get metadata info on a track
The track.getInfo method is a read operation that uses HTTP GET.
http://ws.audioscrobbler.com/2.0/method=track.getInfo
&track="Ring of Fire"
&artist="Johnny Cash"
&username="MrHat"
&api_key=AA25BB53CC45DD85EE22FF30GG67HH64
Parameters
mbid (Optional) : The musicbrainz id for the track
track (Required (unless mbid)] : The track name
artist (Required (unless mbid)] : The artist name
username (Optional) : The username for the context of the request. If supplied, the user's playcount for this track and whether they have loved the track is included in the response.
autocorrect[0|1] (Optional) : Transform misspelled artist and track names into correct artist and track names, returning the correct version instead. The corrected artist and track name will be returned in the response.
api_key (Required) : A Last.fm API key.
Sample Response
<track>
<id>1019999</id>
<name>Ring of Fire</name>
<mbid/>
<url>http://www.last.fm/music/JohnnyCash/_/RingOfFire</url>
<duration>240000</duration>
<streamable fulltrack="1">1</streamable>
<listeners>69572</listeners>
<playcount>281445</playcount>
<artist>
<name>Johnny Cash</name>
<mbid>bfcc6d75-a6a5-4bc6-8282-47aec8531818</mbid>
<url>http://www.last.fm/music/JohnnyCash</url>
</artist>
<album position="1">
<artist>Johnny Cash</artist>
<title>Ring of Fire</title>
<mbid>61bf0388-b8a9-48f4-81d1-7eb02706dfb0</mbid>
<url>http://www.last.fm/music/JohnnyCash/RingOfFire</url>
<image size="small">http://userserveak.last.fm/serve/34/8674593.jpg</image>
<image size="medium">http://userserveak.last.fm/serve/64/8674593.jpg</image>
<image size="large">http://userserveak.last.fm/serve/126/8674593.jpg</image>
</album>
<toptags>
<tag>
<name>Country</name>
<url>http://www.last.fm/tag/country</url>
</tag>
...
</toptags>
<wiki>
<published>Sun, 27 Jul 2008 15:44:58 +0000</published>
<summary>...</summary>
<content>...</content>
</wiki>
</track>
Summary
Website: Last.fm Web Services - http://www.last.fm/api
Documentation: http://www.last.fm/api/intro
Service endpoint: http://ws.audioscrobbler.com/2.0/
Supported HTTP operations: GET, POST
Usage fees: Free; must register for an API account
Comments:
The API is well-conceived and full-featured. Perhaps the most appealing aspect is the simplicity of method calls. The difference in how parameters are transmitted in GET requests (in the URI) versus POST requests (in the request body) is a distinctive feature that developers need to understand for this particular API. The only criticism I have for the documentation is that it should explain exactly how parameters are transmitted in the request body. In particular, the documentation should provide explicit code examples of how parameters are specified in GET and POST requests.
