Last.fm Album API

Methods for retrieving album metadata and managing album tags

Documentation

Specifications

Schemas & Data

Other Resources

OpenAPI Specification

last-fm-album-api-openapi.yml Raw ↑
openapi: 3.0.3
info:
  title: Last.fm Album API
  description: The Last.fm API provides access to the Last.fm music platform, enabling developers to retrieve music metadata for artists, albums, and tracks; read and write user scrobble data; explore personalized recommendations; access global and geographic music charts; search the music catalog; and retrieve user listening histories and social data such as friends and loved tracks. Authentication is required for write operations including scrobbling. The API uses REST over HTTP with responses available in JSON or XML format.
  version: 2.0.0
  contact:
    name: Last.fm API Support
    url: https://www.last.fm/api
  termsOfService: https://www.last.fm/api/tos
  license:
    name: Last.fm API Terms of Service
    url: https://www.last.fm/api/tos
servers:
- url: https://ws.audioscrobbler.com/2.0
  description: Last.fm API endpoint
security: []
tags:
- name: Album
  description: Methods for retrieving album metadata and managing album tags
paths:
  /:
    get:
      operationId: album_getInfo
      summary: Get album info
      description: Get the metadata and tracklisting for an album on Last.fm using the album name or a MusicBrainz id.
      tags:
      - Album
      parameters:
      - name: method
        in: query
        required: true
        schema:
          type: string
          enum:
          - album.getInfo
        description: API method name
      - name: artist
        in: query
        required: false
        schema:
          type: string
        description: The artist name. Required unless mbid is provided.
      - name: album
        in: query
        required: false
        schema:
          type: string
        description: The album name. Required unless mbid is provided.
      - name: mbid
        in: query
        required: false
        schema:
          type: string
        description: The MusicBrainz ID for the album.
      - name: autocorrect
        in: query
        required: false
        schema:
          type: integer
          enum:
          - 0
          - 1
        description: Transform misspelled artist names into correct artist names (0 or 1).
      - name: username
        in: query
        required: false
        schema:
          type: string
        description: The username for the context of the request. Includes playcount in response.
      - name: lang
        in: query
        required: false
        schema:
          type: string
        description: The language to return the biography in, expressed as an ISO 639 alpha-2 code.
      - name: api_key
        in: query
        required: true
        schema:
          type: string
        description: A Last.fm API key.
      - name: format
        in: query
        required: false
        schema:
          type: string
          enum:
          - json
          - xml
        description: The response format (default is xml).
      responses:
        '200':
          description: Successful album info response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlbumInfoResponse'
    post:
      operationId: album_addTags
      summary: Add tags to an album
      description: Tag an album using a list of user supplied tags.
      tags:
      - Album
      parameters:
      - name: method
        in: query
        required: true
        schema:
          type: string
          enum:
          - album.addTags
      - name: artist
        in: query
        required: true
        schema:
          type: string
        description: The artist name.
      - name: album
        in: query
        required: true
        schema:
          type: string
        description: The album name.
      - name: tags
        in: query
        required: true
        schema:
          type: string
        description: A comma delimited list of user supplied tags to apply to this album. Accepts a maximum of 10 tags.
      - name: api_key
        in: query
        required: true
        schema:
          type: string
        description: A Last.fm API key.
      - name: api_sig
        in: query
        required: true
        schema:
          type: string
        description: A Last.fm method signature. See authentication.
      - name: sk
        in: query
        required: true
        schema:
          type: string
        description: A session key generated by authenticating a user via the authentication API.
      responses:
        '200':
          description: Tags added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
      security:
      - SessionKey: []
components:
  schemas:
    Artist:
      type: object
      properties:
        name:
          type: string
        mbid:
          type: string
        url:
          type: string
        image:
          type: array
          items:
            $ref: '#/components/schemas/Image'
    AlbumInfoResponse:
      type: object
      properties:
        album:
          type: object
          properties:
            name:
              type: string
            artist:
              type: string
            id:
              type: string
            mbid:
              type: string
            url:
              type: string
            releasedate:
              type: string
            image:
              type: array
              items:
                $ref: '#/components/schemas/Image'
            listeners:
              type: string
            playcount:
              type: string
            toptags:
              type: object
              properties:
                tag:
                  type: array
                  items:
                    $ref: '#/components/schemas/Tag'
            tracks:
              type: object
              properties:
                track:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                      duration:
                        type: integer
                      mbid:
                        type: string
                      url:
                        type: string
                      artist:
                        $ref: '#/components/schemas/Artist'
    Image:
      type: object
      properties:
        '#text':
          type: string
          description: Image URL
        size:
          type: string
          enum:
          - small
          - medium
          - large
          - extralarge
          - mega
    Tag:
      type: object
      properties:
        name:
          type: string
        url:
          type: string
    StatusResponse:
      type: object
      properties:
        lfm:
          type: object
          properties:
            status:
              type: string
              enum:
              - ok
              - failed
  securitySchemes:
    ApiKey:
      type: apiKey
      in: query
      name: api_key
      description: A Last.fm API key obtained from https://www.last.fm/api/account/create
    SessionKey:
      type: apiKey
      in: query
      name: sk
      description: A session key obtained via the Last.fm authentication flow (auth.getSession or auth.getMobileSession)
externalDocs:
  description: Last.fm API Documentation
  url: https://www.last.fm/api/intro
x-paths:
  artist_getInfo:
    get:
      operationId: artist_getInfo
      summary: Get artist info
      description: Get the metadata for an artist on Last.fm. Includes biography, truncated at 300 characters.
      tags:
      - Artist
      parameters:
      - name: method
        in: query
        required: true
        schema:
          type: string
          enum:
          - artist.getInfo
      - name: artist
        in: query
        required: false
        schema:
          type: string
        description: The artist name. Required unless mbid is provided.
      - name: mbid
        in: query
        required: false
        schema:
          type: string
        description: The MusicBrainz ID for the artist. Takes priority over artist parameter if set.
      - name: lang
        in: query
        required: false
        schema:
          type: string
        description: The language to return the biography in, expressed as an ISO 639 alpha-2 code.
      - name: autocorrect
        in: query
        required: false
        schema:
          type: integer
          enum:
          - 0
          - 1
        description: Transform misspelled artist names into correct artist names (0 or 1).
      - name: username
        in: query
        required: false
        schema:
          type: string
        description: The username for the context of the request. Includes the user's playcount for this artist.
      - name: api_key
        in: query
        required: true
        schema:
          type: string
        description: A Last.fm API key.
      - name: format
        in: query
        required: false
        schema:
          type: string
          enum:
          - json
          - xml
      responses:
        '200':
          description: Successful artist info response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtistInfoResponse'
  artist_getSimilar:
    get:
      operationId: artist_getSimilar
      summary: Get similar artists
      description: Get all the artists similar to this artist.
      tags:
      - Artist
      parameters:
      - name: method
        in: query
        required: true
        schema:
          type: string
          enum:
          - artist.getSimilar
      - name: artist
        in: query
        required: false
        schema:
          type: string
      - name: mbid
        in: query
        required: false
        schema:
          type: string
      - name: autocorrect
        in: query
        required: false
        schema:
          type: integer
          enum:
          - 0
          - 1
      - name: limit
        in: query
        required: false
        schema:
          type: integer
        description: Limit the number of similar artists returned.
      - name: api_key
        in: query
        required: true
        schema:
          type: string
      - name: format
        in: query
        required: false
        schema:
          type: string
          enum:
          - json
          - xml
      responses:
        '200':
          description: List of similar artists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimilarArtistsResponse'
  artist_search:
    get:
      operationId: artist_search
      summary: Search for an artist
      description: Search for an artist by name. Returns artist matches sorted by relevance.
      tags:
      - Artist
      parameters:
      - name: method
        in: query
        required: true
        schema:
          type: string
          enum:
          - artist.search
      - name: artist
        in: query
        required: true
        schema:
          type: string
        description: The artist name to search for.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 30
        description: The number of results to fetch per page. Defaults to 30.
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
        description: The page number to fetch. Defaults to first page.
      - name: api_key
        in: query
        required: true
        schema:
          type: string
      - name: format
        in: query
        required: false
        schema:
          type: string
          enum:
          - json
          - xml
      responses:
        '200':
          description: Artist search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtistSearchResponse'
  track_scrobble:
    post:
      operationId: track_scrobble
      summary: Scrobble tracks
      description: Used to add a track-play to a user's profile. Accepts up to 50 batch scrobbles. Requires authentication via session key.
      tags:
      - Track
      parameters:
      - name: method
        in: query
        required: true
        schema:
          type: string
          enum:
          - track.scrobble
      - name: artist[i]
        in: query
        required: true
        schema:
          type: string
        description: The artist name (use index i for batch scrobbles, e.g. artist[0]).
      - name: track[i]
        in: query
        required: true
        schema:
          type: string
        description: The track name (use index i for batch scrobbles).
      - name: timestamp[i]
        in: query
        required: true
        schema:
          type: integer
        description: The time the track started playing, in UNIX timestamp format.
      - name: album[i]
        in: query
        required: false
        schema:
          type: string
        description: The album name.
      - name: albumArtist[i]
        in: query
        required: false
        schema:
          type: string
        description: The album artist, if different from the track artist.
      - name: trackNumber[i]
        in: query
        required: false
        schema:
          type: integer
        description: The track number of the track on the album.
      - name: mbid[i]
        in: query
        required: false
        schema:
          type: string
        description: The MusicBrainz Track ID.
      - name: duration[i]
        in: query
        required: false
        schema:
          type: integer
        description: The length of the track in seconds.
      - name: chosenByUser[i]
        in: query
        required: false
        schema:
          type: integer
          enum:
          - 0
          - 1
        description: Set to 1 if the user chose this song, or 0 if the song was chosen by someone else (radio, random, etc).
      - name: api_key
        in: query
        required: true
        schema:
          type: string
      - name: api_sig
        in: query
        required: true
        schema:
          type: string
      - name: sk
        in: query
        required: true
        schema:
          type: string
        description: A session key generated by authenticating a user.
      responses:
        '200':
          description: Scrobble response with accepted and ignored counts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScrobbleResponse'
      security:
      - SessionKey: []
  track_updateNowPlaying:
    post:
      operationId: track_updateNowPlaying
      summary: Update now playing
      description: Notify Last.fm that a user has started listening to a track. Requires authentication.
      tags:
      - Track
      parameters:
      - name: method
        in: query
        required: true
        schema:
          type: string
          enum:
          - track.updateNowPlaying
      - name: artist
        in: query
        required: true
        schema:
          type: string
      - name: track
        in: query
        required: true
        schema:
          type: string
      - name: album
        in: query
        required: false
        schema:
          type: string
      - name: albumArtist
        in: query
        required: false
        schema:
          type: string
      - name: trackNumber
        in: query
        required: false
        schema:
          type: integer
      - name: mbid
        in: query
        required: false
        schema:
          type: string
      - name: duration
        in: query
        required: false
        schema:
          type: integer
      - name: api_key
        in: query
        required: true
        schema:
          type: string
      - name: api_sig
        in: query
        required: true
        schema:
          type: string
      - name: sk
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Now playing status updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NowPlayingResponse'
      security:
      - SessionKey: []
  track_getInfo:
    get:
      operationId: track_getInfo
      summary: Get track info
      description: Get the metadata for a track on Last.fm using the artist/track name or a MusicBrainz id.
      tags:
      - Track
      parameters:
      - name: method
        in: query
        required: true
        schema:
          type: string
          enum:
          - track.getInfo
      - name: artist
        in: query
        required: false
        schema:
          type: string
      - name: track
        in: query
        required: false
        schema:
          type: string
      - name: mbid
        in: query
        required: false
        schema:
          type: string
      - name: autocorrect
        in: query
        required: false
        schema:
          type: integer
          enum:
          - 0
          - 1
      - name: username
        in: query
        required: false
        schema:
          type: string
      - name: api_key
        in: query
        required: true
        schema:
          type: string
      - name: format
        in: query
        required: false
        schema:
          type: string
          enum:
          - json
          - xml
      responses:
        '200':
          description: Track info response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackInfoResponse'
  track_search:
    get:
      operationId: track_search
      summary: Search for a track
      description: Search for a track by track name. Returns track matches sorted by relevance.
      tags:
      - Track
      parameters:
      - name: method
        in: query
        required: true
        schema:
          type: string
          enum:
          - track.search
      - name: track
        in: query
        required: true
        schema:
          type: string
        description: The track name to search for.
      - name: artist
        in: query
        required: false
        schema:
          type: string
        description: Narrow your results by specifying an artist.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 30
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
      - name: api_key
        in: query
        required: true
        schema:
          type: string
      - name: format
        in: query
        required: false
        schema:
          type: string
          enum:
          - json
          - xml
      responses:
        '200':
          description: Track search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackSearchResponse'
  track_getSimilar:
    get:
      operationId: track_getSimilar
      summary: Get similar tracks
      description: Returns similar tracks for this track based on listening data.
      tags:
      - Track
      parameters:
      - name: method
        in: query
        required: true
        schema:
          type: string
          enum:
          - track.getSimilar
      - name: artist
        in: query
        required: false
        schema:
          type: string
      - name: track
        in: query
        required: false
        schema:
          type: string
      - name: mbid
        in: query
        required: false
        schema:
          type: string
      - name: autocorrect
        in: query
        required: false
        schema:
          type: integer
          enum:
          - 0
          - 1
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      - name: api_key
        in: query
        required: true
        schema:
          type: string
      - name: format
        in: query
        required: false
        schema:
          type: string
          enum:
          - json
          - xml
      responses:
        '200':
          description: Similar tracks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimilarTracksResponse'
  track_love:
    post:
      operationId: track_love
      summary: Love a track
      description: Love a track for a user profile. Requires authentication.
      tags:
      - Track
      parameters:
      - name: method
        in: query
        required: true
        schema:
          type: string
          enum:
          - track.love
      - name: artist
        in: query
        required: true
        schema:
          type: string
      - name: track
        in: query
        required: true
        schema:
          type: string
      - name: api_key
        in: query
        required: true
        schema:
          type: string
      - name: api_sig
        in: query
        required: true
        schema:
          type: string
      - name: sk
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Track loved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
      security:
      - SessionKey: []
  user_getRecentTracks:
    get:
      operationId: user_getRecentTracks
      summary: Get user recent tracks
      description: Get a list of the recent tracks listened to by this user. Also includes the currently playing track with the nowplaying="true" attribute if the user is currently listening.
      tags:
      - User
      parameters:
      - name: method
        in: query
        required: true
        schema:
          type: string
          enum:
          - user.getRecentTracks
      - name: user
        in: query
        required: true
        schema:
          type: string
        description: The last.fm username to fetch the recent tracks of.
      - name: api_key
        in: query
        required: true
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
          maximum: 200
        description: The number of results to fetch per page. Defaults to 50. Maximum is 200.
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
      - name: from
        in: query
        required: false
        schema:
          type: integer
        description: Beginning timestamp of a range, UNIX timestamp format.
      - name: to
        in: query
        required: false
        schema:
          type: integer
        description: End timestamp of a range, UNIX timestamp format.
      - name: extended
        in: query
        required: false
        schema:
          type: integer
          enum:
          - 0
          - 1
        description: Includes extended data in each artist, and whether the user has loved each track.
      - name: format
        in: query
        required: false
        schema:
          type: string
          enum:
          - json
          - xml
      responses:
        '200':
          description: Recent tracks list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecentTracksResponse'
  user_getInfo:
    get:
      operationId: user_getInfo
      summary: Get user info
      description: Get information about a user profile.
      tags:
      - User
      parameters:
      - name: method
        in: query
        required: true
        schema:
          type: string
          enum:
          - user.getInfo
      - name: user
        in: query
        required: true
        schema:
          type: string
        description: The username to fetch the info for.
      - name: api_key
        in: query
        required: true
        schema:
          type: string
      - name: format
        in: query
        required: false
        schema:
          type: string
          enum:
          - json
          - xml
      responses:
        '200':
          description: User profile information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInfoResponse'
  user_getTopArtists:
    get:
      operationId: user_getTopArtists
      summary: Get user top artists
      description: Get the top artists listened to by a user. You can stipulate a time period.
      tags:
      - User
      parameters:
      - name: method
        in: query
        required: true
        schema:
          type: string
          enum:
          - user.getTopArtists
      - name: user
        in: query
        required: true
        schema:
          type: string
      - name: period
        in: query
        required: false
        schema:
          type: string
          enum:
          - overall
          - 7day
          - 1month
          - 3month
          - 6month
          - 12month
        description: The time period over which to retrieve top artists.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
      - name: api_key
        in: query
        required: true
        schema:
          type: string
      - name: format
        in: query
        required: false
        schema:
          type: string
          enum:
          - json
          - xml
      responses:
        '200':
          description: User top artists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopArtistsResponse'
  user_getTopTracks:
    get:
      operationId: user_getTopTracks
      summary: Get user top tracks
      description: Get the top tracks listened to by a user. You can stipulate a time period.
      tags:
      - User
      parameters:
      - name: method
        in: query
        required: true
        schema:
          type: string
          enum:
          - user.getTopTracks
      - name: user
        in: query
        required: true
        schema:
          type: string
      - name: period
        in: query
        required: false
        schema:
          type: string
          enum:
          - overall
          - 7day
          - 1month
          - 3month
          - 6month
          - 12month
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
      - name: api_key
        in: query
        required: true
        schema:
          type: string
      - name: format
        in: query
        required: false
        schema:
          type: string
          enum:
          - json
          - xml
      responses:
        '200':
          description: User top tracks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopTracksResponse'
  user_getLovedTracks:
    get:
      operationId: user_getLovedTracks
      summary: Get user loved tracks
      description: A paginated list of all the tracks a user has loved.
      tags:
      - User
      parameters:
      - name: method
        in: query
        required: true
        schema:
          type: string
          enum:
          - user.getLovedTracks
      - name: user
        in: query
        required: true
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
      - name: api_key
        in: query
        required: true
        schema:
          type: string
      - name: format
        in: query
        required: false
        schema:
          type: string
          enum:
          - json
          - xml
      responses:
        '200':
          description: Loved tracks list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LovedTracksResponse'
  user_getFriends:
    get:
      operationId: user_getFriends
      summary: Get user friends
      description: Get a list of the user's friends on Last.fm.
      tags:
      - User
      parameters:
      - name: method
        in: query
        required: true
        schema:
          type: string
          enum:
          - user.getFriends
      - name: user
        in: query
        required: true
        schema:
          type: string
      - name: recenttracks
        in: query
        required: false
        schema:
          type: integer
          enum:
          - 0
          - 1
        description: Whether or not to include information about friends' recent listening.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
      - name: api_key
        in: query
        required: true
        schema:
          type: string
      - name: format
        in: query
        required: false
        schema:
          type: string
          enum:
          - json
          - xml
      responses:
        '200':
          description: User friends list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FriendsResponse'
  chart_getTopArtists:
    get:
      operationId: chart_getTopArtists
      summary: Get top artists chart
      description: Get the top artists chart.
      tags:
      - Chart
      parameters:
      - name: method
        in: query
        required: true
        schema:
          type: string
          enum:
          - chart.getTopArtists
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
      - name: api_key
        in: query
        required: true
        schema:
          type: string
      - name: format
        in: query
        required: false
        schema:
          type: string
          enum:
          - json
          - xml
      responses:
        '200':
          description: Top artists chart
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChartArtistsResponse'
  chart_getTopTracks:
    get:
      operationId: chart_getTopTracks
      summary: Get top tracks chart
      description: Get the top tracks chart.
      tags:
      - Chart
      parameters:
      - name: method
        in: query
        required: true
        schema:
          type: string
          enum:
          - chart.getTopTracks
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
      - name: api_key
        in: query
        required: true
        schema:
          type: string
      - name: format
        in: query
        required: false
        schema:
          type: string
          enum:
          - json
          - xml
      responses:
        '200':
          description: Top tracks chart
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChartTracksResponse'
  chart_getTopTags:
    get:
      operationId: chart_getTopTags
      summary: Get top tags chart
      description: Get the top tags chart.
      tags:
      - Chart
      parameters:
      - name: method
        in: query
        required: true
    

# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/last-fm/refs/heads/main/openapi/last-fm-album-api-openapi.yml