### Basic GET Request Example

Source: https://www.last.fm/api/rest

This is an example of a basic GET request to the artist.getSimilar method, requiring an api_key and the method parameter.

```http
http://ws.audioscrobbler.com/2.0/?method=artist.getSimilar&api_key=xxx...
```

--------------------------------

### User Radio Station Examples

Source: https://www.last.fm/api/radio

Examples of constructing station URLs for user-based radio stations.

```text
lastfm://user/last.hq/personal
```

```text
lastfm://user/last.hq/loved
```

```text
lastfm://user/last.hq/recommended
```

```text
lastfm://user/last.hq/neighbours
```

--------------------------------

### Artist Radio Station Examples

Source: https://www.last.fm/api/radio

Examples of constructing station URLs for artist-based radio stations.

```text
lastfm://artist/cher/similarartists
```

```text
lastfm://artist/cher/fans
```

--------------------------------

### API Method Signature Construction Example

Source: https://www.last.fm/api/desktopauth

Example of constructing the string to be hashed for an API method signature. Parameters are ordered alphabetically and concatenated.

```text
**api_key**xxxxxxxx**method**auth.getSession**token**xxxxxxx
```

--------------------------------

### Tag Radio Station Example

Source: https://www.last.fm/api/radio

Example of constructing a station URL for tag-based radio stations.

```text
lastfm://globaltags/disco
```

--------------------------------

### XML Example URL for chart.getTopTracks

Source: https://www.last.fm/api/show/chart.getTopTracks

This is an example URL to fetch the top tracks chart in XML format. It requires a valid Last.fm API key.

```url
/2.0/?method=chart.gettoptracks&api_key=YOUR_API_KEY
```

--------------------------------

### Constructing API Call String

Source: https://www.last.fm/api/authspec

This example shows how to construct the string for API signature generation by alphabetically ordering and concatenating parameters, excluding 'format' and 'callback'.

```text
api_keyxxxxxxxxxxmethodauth.getSessiontokenyyyyyy
```

--------------------------------

### User GetWeeklyChartList XML Example URL

Source: https://www.last.fm/api/show/user.getWeeklyChartList

Example URL for fetching weekly chart list in XML format. Requires a valid Last.fm username and API key.

```url
/2.0/?method=user.getweeklychartlist&user=rj&api_key=YOUR_API_KEY(opens new window)
```

--------------------------------

### JSON Example URL for chart.getTopTracks

Source: https://www.last.fm/api/show/chart.getTopTracks

This is an example URL to fetch the top tracks chart in JSON format. It requires a valid Last.fm API key.

```url
/2.0/?method=chart.gettoptracks&api_key=YOUR_API_KEY&format=json
```

--------------------------------

### Constructing API Signature Example

Source: https://www.last.fm/api/mobileauth

Illustrates the construction of an API method signature by alphabetically ordering parameters, concatenating them, appending the secret, and generating an MD5 hash. This is crucial for signing authenticated API calls.

```text
**api_key**xxxxxxxx**method**auth.getMobileSession**password**xxxxxxx**username**xxxxxxxx
```

```text
api signature = md5("api_keyxxxxxxxxmethodauth.getMobileSession
                         passwordxxxxxxxusernamexxxxxxxxmysecret")
```

--------------------------------

### Receive Authentication Token

Source: https://www.last.fm/api/webauth

After user authorization, Last.fm redirects to your callback URL with an authentication token as a GET variable. This example shows how the token might be appended.

```http
<callback_url>/?token=xxxxxxx

```

```http
<callback_url>&token=xxxxxxx

```

--------------------------------

### JSON Success Response Example

Source: https://www.last.fm/api/rest

An example of a successful API response in JSON format, showing nested objects and arrays for tag matches.

```json
{
"results": {
    "tagmatches": {
      "tag": [{"name": "disco", "count": "55483", "url": "www.last.fm\/tag\/disco"},
      ...
      {"name": "disco pop", "count": "160", "url": "www.last.fm\/tag\/disco%20pop"}]
    },
    "for": "disco"
  }
}
```

--------------------------------

### User GetWeeklyChartList JSON Example URL

Source: https://www.last.fm/api/show/user.getWeeklyChartList

Example URL for fetching weekly chart list in JSON format. Requires a valid Last.fm username and API key.

```url
/2.0/?method=user.getweeklychartlist&user=rj&api_key=YOUR_API_KEY&format=json(opens new window)
```

--------------------------------

### Generating API Signature

Source: https://www.last.fm/api/authspec

This example demonstrates the final step in API signature generation: appending the secret key to the ordered parameter string and calculating the MD5 hash.

```text
api signature = md5("api_keyxxxxxxxxxxmethodauth.getSessiontokenyyyyyyilovecher")
```

--------------------------------

### XSPF Playlist Format Example

Source: https://www.last.fm/api/radio

An example of the XSPF (XML Shareable Playlist Format) structure returned by the radio.getPlaylist API method. This format contains track information and metadata.

```xml
<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>
       ...
            

```

--------------------------------

### Tag.getSimilar API Call (JSON)

Source: https://www.last.fm/api/show/tag.getSimilar

Example URL for retrieving similar tags in JSON format. Requires a tag name and an API key.

```bash
/2.0/?method=tag.getsimilar&tag=disco&api_key=YOUR_API_KEY&format=json
```

--------------------------------

### Tag.getSimilar API Call (XML)

Source: https://www.last.fm/api/show/tag.getSimilar

Example URL for retrieving similar tags in XML format. Requires a tag name and an API key.

```bash
/2.0/?method=tag.getsimilar&tag=disco&api_key=YOUR_API_KEY
```

--------------------------------

### Example XML-RPC Request

Source: https://www.last.fm/api/xmlrpc

This snippet shows the structure of an XML-RPC POST request to the Last.fm API, specifically for the 'user.gettoptags' method. Parameters are sent as named arguments within a struct.

```xml
<methodCall>
 <methodName>user.gettoptags</methodName>
 <params>
  <param>
   <value>
    <struct>
     <member>
      <name>user</name>
      <value>
       <string>joanofarctan</string>
      </value>
     </member>
     <member>
      <name>api_key</name>
      <value>
       <string>b25b959554ed76058ac220b7b2e0a026</string>
      </value>
     </member>
    </struct>
   </value>
  </param>
 </params>
</methodCall>
```

--------------------------------

### XML-RPC Request Example

Source: https://www.last.fm/api/xmlrpc

This snippet shows how to structure an XML-RPC POST request to the Last.fm API. Parameters are sent as named arguments within a struct in the first param node.

```APIDOC
## XML-RPC Requests

Send xml-rpc requests as HTTP POST requests to http://ws.audioscrobbler.com/2.0/.

### Method
POST

### Endpoint
http://ws.audioscrobbler.com/2.0/

### Description
Send XML-RPC requests to the Last.fm API. Parameters should be provided as named arguments within a struct in the first param node.

### Request Body Example
```xml
<methodCall>
 <methodName>user.gettoptags</methodName>
 <params>
  <param>
   <value>
    <struct>
     <member>
      <name>user</name>
      <value>
       <string>joanofarctan</string>
      </value>
     </member>
     <member>
      <name>api_key</name>
      <value>
       <string>b25b959554ed76058ac220b7b2e0a026</string>
      </value>
     </member>
    </struct>
   </value>
  </param>
 </params>
</methodCall>
```

### Response
XML-RPC requests will receive responses in XML-RPC format by default. Refer to the XML-RPC specification for more details.
```

--------------------------------

### Example XML Response for Missing Parameter

Source: https://www.last.fm/api/scrobbling

This XML response indicates a missing required parameter, 'artist', resulting in a 'failed' status and an error code of 6.

```xml
<?xml version="1.0" encoding="utf-8"?>
<lfm status="failed">
    <error code="6">Missing required parameter artist</error>
</lfm>
```

--------------------------------

### MD5 Hashing for API Signature

Source: https://www.last.fm/api/desktopauth

Example of generating an MD5 hash for an API method signature by appending the secret to the concatenated parameter string.

```text
api signature = md5("api_keyxxxxxxxxmethodauth.getSessiontokenxxxxxxxmysecret")
```

--------------------------------

### Sample Response for auth.getSession

Source: https://www.last.fm/api/show/auth.getSession

This is a sample XML response received after successfully fetching a session key for a user.

```xml
<lfm status="ok">
  <session>
    <name>MyLastFMUsername</name>
    <key>d580d57f32848f5dcf574d1ce18d78b2</key>
     <subscriber>0</subscriber>
  </session>
</lfm>
```

--------------------------------

### Sample XML Response for library.getartists

Source: https://www.last.fm/api/show/library.getArtists

This snippet shows a sample XML response structure for the library.getartists method, illustrating the data returned for each artist.

```xml
<artists user="RJ" page="1" perPage="50" totalPages="20">
  <artist rank="1">
    <name>Dream Theater</name>
    <playcount>1346</playcount>
    <tagcount>0</tagcount>
    <mbid>28503ab7-8bf2-4666-a7bd-2644bfc7cb1d</mbid>
    <url>http://www.last.fm/music/Dream+Theater</url>
    <streamable>1</streamable>
    <image size="small">http://userserve-ak.last.fm/serve/50/95853.jpg</image>
    <image size="medium">http://userserve-ak.last.fm/serve/85/95853.jpg</image>
    <image size="large">http://userserve-ak.last.fm/serve/160/95853.jpg</image>
  </artist>
  ...
</artists>
```

--------------------------------

### Request Authorization (Desktop Applications)

Source: https://www.last.fm/api/authspec

Desktop applications should first fetch a token and then redirect the user to this URL to authorize the token.

```APIDOC
## GET /api/auth

### Description
Request authorization from the user for desktop applications after obtaining a token.

### Method
GET

### Endpoint
http://www.last.fm/api/auth/

### Parameters
#### Query Parameters
- **api_key** (string) - Required - Your Last.fm API key.
- **token** (string) - Required - The authentication token obtained via auth.getToken.
```

--------------------------------

### track.updateNowPlaying

Source: https://www.last.fm/api/scrobbling

Lets a client notify Last.fm that a user has started listening to a track. This is optional but recommended and should be sent as soon as a user starts listening to a track. Requests must be sent as HTTP POST requests to http://ws.audioscrobbler.com/2.0/ with form urlencoded parameters in the body and must be authenticated.

```APIDOC
## track.updateNowPlaying

### Description
Sends "Now Playing" information to Last.fm, indicating the track a user is currently listening to. This updates the user's profile but does not affect charts. It's recommended to send this request as soon as a track begins playing.

### Method
POST

### Endpoint
http://ws.audioscrobbler.com/2.0/

### Parameters
#### Request Body
- **track** (string) - Required - The title of the track.
- **artist** (string) - Required - The name of the artist.
- **album** (string) - Optional - The name of the album.
- **duration** (integer) - Optional - The duration of the track in seconds.
- **chosenByUser** (boolean) - Optional - Indicates if the scrobble was directly chosen by the user (defaults to true).
- **api_key** (string) - Required - Your Last.fm API key.
- **sk** (string) - Required - A session key for authentication.

### Request Example
```
POST http://ws.audioscrobbler.com/2.0/
Content-Type: application/x-www-form-urlencoded

track=Hey+Jude&artist=The+Beatles&album=Let+It+Be&duration=431&api_key=YOUR_API_KEY&sk=YOUR_SESSION_KEY
```

### Response
#### Success Response (200)
- **lfm status** (string) - "ok"

#### Response Example
```json
{
  "nowplaying": {
    "track": {"#text": "Hey Jude", "#attributes": {"artist": "The Beatles", "album": "Let It Be"}},
    "artist": {"#text": "The Beatles", "#attributes": {"mbid": "..."}},
    "album": {"#text": "Let It Be", "#attributes": {"mbid": "..."}},
    "duration": "431",
    "user": "username",
    "@attr": {"nowplaying": "true"}
  }
}
```

### Error Handling
- **HTTP Status Code**: Indicates general request success or failure.
- **lfm status attribute**: "ok" or "failed".
- **lfm error code**: Provides specific error details when status is "failed".
```

--------------------------------

### artist.getInfo

Source: https://www.last.fm/api/show/artist.getInfo

Get the metadata for an artist. Includes biography, truncated at 300 characters.

```APIDOC
## GET /2.0/

### Description
Retrieves metadata for a specified artist, including a truncated biography.

### Method
GET

### Endpoint
/2.0/

### Parameters
#### Query Parameters
- **method** (string) - Required - artist.getinfo
- **artist** (string) - Required (unless mbid) - The artist name.
- **mbid** (string) - Optional - The musicbrainz id for the artist.
- **lang** (string) - Optional - The language to return the biography in, expressed as an ISO 639 alpha-2 code.
- **autocorrect** (integer) - Optional - Transform misspelled artist names into correct artist names, returning the correct version instead. The corrected artist name will be returned in the response. Accepts 0 or 1.
- **username** (string) - Optional - The username for the context of the request. If supplied, the user's playcount for this artist is included in the response.
- **api_key** (string) - Required - A Last.fm API key.

### Request Example
```json
{
  "example": "/2.0/?method=artist.getinfo&artist=Cher&api_key=YOUR_API_KEY&format=json"
}
```

### Response
#### Success Response (200)
- **artist** (object) - Contains artist details.
  - **name** (string) - The name of the artist.
  - **mbid** (string) - The musicbrainz id of the artist.
  - **url** (string) - The URL to the artist's page on Last.fm.
  - **image** (array) - An array of image objects with different sizes.
  - **streamable** (integer) - Indicates if the artist is streamable (1) or not (0).
  - **stats** (object) - Contains statistics about the artist.
    - **listeners** (integer) - The number of listeners.
    - **plays** (integer) - The number of plays.
  - **similar** (object) - Contains a list of similar artists.
  - **tags** (object) - Contains a list of tags associated with the artist.
  - **bio** (object) - Contains the artist's biography.
    - **published** (string) - The publication date of the biography.
    - **summary** (string) - A summary of the biography.
    - **content** (string) - The full biography content.
}
```

#### Response Example
```json
{
  "artist": {
    "name": "Cher",
    "mbid": "bfcc6d75-a6a5-4bc6-8282-47aec8531818",
    "url": "http://www.last.fm/music/Cher",
    "image": [
      {
        "size": "small",
        "#text": "http://userserve-ak.last.fm/serve/50/285717.jpg"
      },
      {
        "size": "medium",
        "#text": "http://userserve-ak.last.fm/serve/85/285717.jpg"
      },
      {
        "size": "large",
        "#text": "http://userserve-ak.last.fm/serve/160/285717.jpg"
      }
    ],
    "streamable": 1,
    "stats": {
      "listeners": 196440,
      "plays": 1599101
    },
    "similar": {
      "artist": [
        {
          "name": "Madonna",
          "url": "http://www.last.fm/music/Madonna",
          "image": [
            {
              "size": "small",
              "#text": "http://userserve-ak.last.fm/serve/50/5112299.jpg"
            },
            {
              "size": "medium",
              "#text": "http://userserve-ak.last.fm/serve/85/5112299.jpg"
            },
            {
              "size": "large",
              "#text": "http://userserve-ak.last.fm/serve/160/5112299.jpg"
            }
          ]
        }
      ]
    },
    "tags": {
      "tag": [
        {
          "name": "pop",
          "url": "http://www.last.fm/tag/pop"
        }
      ]
    },
    "bio": {
      "published": "Thu, 13 Mar 2008 03:59:18 +0000",
      "summary": "...",
      "content": "..."
    }
  }
}
```

### Errors
- **2**: Invalid service - This service does not exist
- **3**: Invalid Method - No method with that name in this package
- **4**: Authentication Failed - You do not have permissions to access the service
- **5**: Invalid format - This service doesn't exist in that format
- **6**: Invalid parameters - Your request is missing a required parameter
- **7**: Invalid resource specified
- **8**: Operation failed - Something else went wrong
- **9**: Invalid session key - Please re-authenticate
- **10**: Invalid API key - You must be granted a valid key by last.fm
- **11**: Service Offline - This service is temporarily offline. Try again later.
- **13**: Invalid method signature supplied
- **16**: There was a temporary error processing your request. Please try again
- **26**: Suspended API key - Access for your account has been suspended, please contact Last.fm
- **29**: Rate limit exceeded - Your IP has made too many requests in a short period
```

--------------------------------

### Sample artist.getInfo XML Response

Source: https://www.last.fm/api/show/artist.getInfo

This is a sample XML response for the artist.getInfo method, showing artist details, similar artists, tags, and biography.

```xml
<artist>
  <name>Cher</name>
  <mbid>bfcc6d75-a6a5-4bc6-8282-47aec8531818</mbid>
  <url>http://www.last.fm/music/Cher</url>
  <image size="small">http://userserve-ak.last.fm/serve/50/285717.jpg</image>
  <image size="medium">http://userserve-ak.last.fm/serve/85/285717.jpg</image>
  <image size="large">http://userserve-ak.last.fm/serve/160/285717.jpg</image>
  <streamable>1</streamable>
  <stats>
    <listeners>196440</listeners>
    <plays>1599101</plays>
  </stats>
  <similar>
    <artist>
      <name>Madonna</name>
      <url>http://www.last.fm/music/Madonna</url>
      <image size="small">http://userserve-ak.last.fm/serve/50/5112299.jpg</image>
      <image size="medium">http://userserve-ak.last.fm/serve/85/5112299.jpg></image>
      <image size="large">http://userserve-ak.last.fm/serve/160/5112299.jpg</image>
    </artist>
    ...
  </similar>
  <tags>
    <tag>
      <name>pop</name>
      <url>http://www.last.fm/tag/pop</url>
    </tag>
    ...
  </tags>
  <bio>
    <published>Thu, 13 Mar 2008 03:59:18 +0000</published>
    <summary>...</summary>
    <content>...</content>
  </bio>
</artist>
```

--------------------------------

### Get Mobile Session

Source: https://www.last.fm/api/authspec

Mobile applications use this method to authenticate users by sending their credentials directly.

```APIDOC
## POST auth.getMobileSession

### Description
Authenticate users and create a session for mobile applications.

### Method
POST

### Endpoint
(Not specified, assumed to be a Last.fm API endpoint, must be over HTTPS)

### Parameters
#### Request Body
- **password** (string) - Required - The user's password in plaintext.
- **username** (string) - Required - The user's Last.fm username.
- **api_key** (string) - Required - A Last.fm API key.
- **api_sig** (string) - Required - A Last.fm method signature.
```

--------------------------------

### Original XML Response Example

Source: https://www.last.fm/api/rest

This shows the original XML structure that is translated into the JSON success response format.

```xml
<?xml version="1.0" encoding="utf-8"?>
<lfm status="ok">
 <results for="disco" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
    <opensearch:Query role="request" searchTerms="disco" startPage="1" />
    <opensearch:totalResults>2641</opensearch:totalResults>
    <opensearch:startIndex>0</opensearch:startIndex>
    <opensearch:itemsPerPage>20</opensearch:itemsPerPage>
    <tagmatches>
      <tag>
        <name>disco</name>
        <count>55483</count>
        <url>www.last.fm/tag/disco</url>
      </tag>
      ...
      <tag>
        <name>disco pop</name>
        <count>160</count>
        <url>www.last.fm/tag/disco%20pop</url>
      </tag>
    </tagmatches>
  </results>
</lfm>
```

--------------------------------

### Sample XML Response for chart.getTopTracks

Source: https://www.last.fm/api/show/chart.getTopTracks

This is a sample XML response structure for the chart.getTopTracks method, showing track details like name, playcount, listeners, and artist information.

```xml
<tracks page="1" perPage="50" totalPages="20" total="1000">
  <track>
    <name>Dark Fantasy</name>
    <playcount>124394</playcount>
    <listeners>42141</listeners>
    <mbid/>
    <url>http://www.last.fm/music/Kanye+West/_/Dark+Fantasy</url>
    <streamable fulltrack="0">0</streamable>
    <artist>
      <name>Kanye West</name>
      <mbid>164f0d73-1234-4e2c-8743-d77bf2191051</mbid>
      <url>http://www.last.fm/music/Kanye+West</url>
    </artist>
  </track>
  ...
</tracks>
```

--------------------------------

### Fetch Request Token (Desktop Applications)

Source: https://www.last.fm/api/authspec

Desktop applications must first call this method to obtain an authentication token before requesting user authorization.

```APIDOC
## POST auth.getToken

### Description
Fetch an authentication token for desktop applications.

### Method
POST

### Endpoint
(Not specified, assumed to be a Last.fm API endpoint)

### Parameters
#### Request Body
- **api_key** (string) - Required - Your 32-character API Key.
- **api_sig** (string) - Required - A 32-character API method signature.
```

--------------------------------

### Desktop Application: Request User Authorization

Source: https://www.last.fm/api/authspec

Open a web browser to this URL for desktop application authorization. Include your API key and the obtained token.

```http
http://www.last.fm/api/auth/?api_key=xxxxxxxxxx&token=yyyyyy
```

--------------------------------

### Example XML Response for Filtered Scrobble

Source: https://www.last.fm/api/scrobbling

This XML response shows a successful scrobble request ('ok' status) where one scrobble was ignored due to bad metadata (artist name filtered).

```xml
<?xml version='1.0' encoding='utf-8'?>
<lfm status="ok">
    <scrobbles accepted="0" ignored="1">
        <scrobble>
            <track corrected="0">Test Track</track>
            <artist corrected="0">Unknown Artist</artist>
            <album corrected="0"></album>
            <albumartist corrected="0"></albumartist>
            <timestamp>1288728940</timestamp>
            <ignoredmessage code="1">
                Artist name failed filter: Unknown Artist
            </ignoredmessage>
        </scrobble>
    </scrobbles>
</lfm>
```

--------------------------------

### Tag.getSimilar Sample Response (XML)

Source: https://www.last.fm/api/show/tag.getSimilar

A sample XML response structure for the tag.getSimilar method, showing similar tags with their names and URLs.

```xml
<similartags tag="Disco">
  <tag>
    <name>high energy</name>
    <url>http://www.last.fm/tag/high energy</url>
    <streamable>1</streamable>
  </tag>
  ...
</similartags>
```

--------------------------------

### Web Application: Authentication Token Callback

Source: https://www.last.fm/api/authspec

Last.fm redirects to your callback URL with an authentication token. Your script should capture this token.

```http
<callback_url>/?token=yyyyyy
```