# Radio API

# Who can I stream radio to?

# Tuning the Radio

The radio API requires authentication. See the authentication how-to.

Once authenticated, you can tune the radio using the radio.tune API method. This takes a station parameter that must correspond to a last.fm protocol station url. Here is the general scheme of these URLs:

lastfm://<stationtype>/<resourcename>/<station-subtype>

Here is a list of the station types currently publicly available, with example protocol URLs:

• Artist
  • Similar Artists Radio (e.g. lastfm://artist/cher/similarartists )
  • Top Fans Radio (e.g. lastfm://artist/cher/fans )
• User
  • Library Radio (e.g. lastfm://user/last.hq/personal )
  • Mix Radio (e.g. lastfm://user/last.hq/loved )
  • Recommendation Radio (e.g. lastfm://user/last.hq/recommended )
  • Neighbours Radio (e.g. lastfm://user/last.hq/neighbours )
• Tag
  • Global Tag Radio (e.g. lastfm://globaltags/disco )

# Fetching Radio Content

Once the station is tuned, use the API method radio.getPlaylist to fetch content in XSPF format (see the XSPF specification). You will need to periodically pull on this XSPF service as it will provide content in small chunks. We recommend you prefetch a new XSPF before reaching the end of the last.

The XSPF will look like this:

<playlist version="1" xmlns="http://xspf.org/ns/0/">
     <title>+Cher+Similar+Artists</title>
     <creator>Last.fm</creator>
     <date>2007-11-26T17:34:38</date>
     <link rel="http://www.last.fm/expiry">3600</link>
     <trackList>
      <track>
       <location>http://play.last.fm/....mp3</location>
       <title>Two People (Live)</title>
       <identifier>8212510</identifier>
       <album>Tina Live In Europe</album>
       <creator>Tina Turner</creator>
       <duration>265000</duration>
       <image>http://images.amazon.com/images/...</image>
       <extension application="http://www.last.fm/">
        <trackauth>12345</trackauth>
        <artistpage>http://www.last.fm/music/Tina+Turner</artistpage>
        <albumpage>http://www.last.fm/music/...</albumpage>
        <trackpage>http://www.last.fm/music/...</trackpage>
        <buyTrackURL>...</buyTrackURL>
        <buyAlbumURL/>
        <freeTrackURL>
        </extension>
      </track>
      <track>
       ...
            

The expiry extension is used to communicate in seconds (from the granting of the XSPF), how long any of the track URLs in your XSPF are valid for. If you request any tracks after this expiry period you will receive errors from our streaming service (see below).

Note the extension node, which holds last.fm specific information relating to the track.

The trackauth extension is now deprecated and can be ignored.

Use the location nodes to fetch individual tracks. All tracks must be requested once and only once, in the order supplied in the XSPF. Requesting the same track multiple times will result in an HTTP error returned from our streamers. Note that the track URLs provided will force an HTTP 302 redirect to the actual track location.

Please ensure your streaming library supports HTTP redirects when fetching tracks

All tracks streamed are encoded as 128kbps MP3 files. We recommend clients begin playback as soon as a reasonable buffer (6-8 seconds) has been fetched. Do not attempt to store the file locally other than maintaining a reasonable buffer.

Pausing playback is strictly not allowed and our streamers will return an error if you attempt to reconnect to the track more than once.

# Streamer Error Codes

• HTTP 403 - Invalid ticket: You may be requesting tracks in the wrong order, your playlist may have expired or you have attempted to fetch the same track URL multiple times.
• HTTP 503 - Unexpected Error: Our streamers are not healthy. Try again later.