openapi: 3.0.3
info:
  title: Last.fm Web Services API (2.0) Album API
  version: '2.0'
  description: 'The Last.fm (AudioScrobbler) Web Services 2.0 API provides programmatic access to

    music metadata, charts, geo-listening data, tags, user listening history, and

    scrobbling. The API is method-dispatched: every request targets the single endpoint

    `https://ws.audioscrobbler.com/2.0/` and identifies the operation via the `method`

    query/body parameter (e.g. `method=track.getInfo`).


    Read methods accept `GET`; write methods (scrobbling, tagging, love/unlove, session

    management) require `POST` with an authenticated session key and a signed

    `api_sig` parameter (MD5 of sorted params + shared secret).


    Responses default to XML; pass `format=json` for JSON.

    '
  termsOfService: https://www.last.fm/api/tos
  contact:
    name: Last.fm API Support
    url: https://www.last.fm/api
    email: partners@last.fm
  license:
    name: Last.fm API Terms of Service
    url: https://www.last.fm/api/tos
servers:
- url: https://ws.audioscrobbler.com/2.0
  description: Production AudioScrobbler endpoint
- url: http://ws.audioscrobbler.com/2.0
  description: Non-TLS endpoint (legacy)
security:
- ApiKeyAuth: []
- SignedAuth: []
tags:
- name: Album
  description: Album metadata, tagging, and search.
paths:
  /:
    get:
      operationId: invokeReadMethod
      summary: Invoke A Read Method
      description: 'Single read-side dispatch endpoint. The `method` parameter selects the

        operation (e.g. `album.getInfo`, `artist.getTopTracks`, `chart.getTopArtists`).

        Use `format=json` for JSON responses.

        '
      tags:
      - Album
      parameters:
      - $ref: '#/components/parameters/MethodParam'
      - $ref: '#/components/parameters/ApiKeyParam'
      - $ref: '#/components/parameters/FormatParam'
      - $ref: '#/components/parameters/CallbackParam'
      - name: artist
        in: query
        schema:
          type: string
        description: Artist name (used by album.*, artist.*, track.* read methods).
      - name: album
        in: query
        schema:
          type: string
        description: Album name (used by album.* methods).
      - name: track
        in: query
        schema:
          type: string
        description: Track name (used by track.* methods).
      - name: mbid
        in: query
        schema:
          type: string
        description: MusicBrainz identifier; takes precedence over artist/album/track names.
      - name: user
        in: query
        schema:
          type: string
        description: Last.fm username (used by user.* methods).
      - name: tag
        in: query
        schema:
          type: string
        description: Tag name (used by tag.* methods).
      - name: country
        in: query
        schema:
          type: string
        description: ISO 3166-1 country name (used by geo.* methods).
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
          maximum: 1000
        description: Max items per page.
      - name: page
        in: query
        schema:
          type: integer
          default: 1
        description: Page number for paginated results.
      - name: period
        in: query
        schema:
          type: string
          enum:
          - overall
          - 7day
          - 1month
          - 3month
          - 6month
          - 12month
        description: Aggregation window for user.getTop* methods.
      - name: autocorrect
        in: query
        schema:
          type: integer
          enum:
          - 0
          - 1
          default: 0
        description: Auto-correct misspelled artist/track names when set to 1.
      - name: username
        in: query
        schema:
          type: string
        description: Username context for personalized fields (playcount, userplaycount).
      responses:
        '200':
          description: Successful response in XML (default) or JSON (`format=json`).
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/AlbumInfoResponse'
                - $ref: '#/components/schemas/ArtistInfoResponse'
                - $ref: '#/components/schemas/TrackInfoResponse'
                - $ref: '#/components/schemas/TagInfoResponse'
                - $ref: '#/components/schemas/UserInfoResponse'
                - $ref: '#/components/schemas/ChartResponse'
                - $ref: '#/components/schemas/GeoResponse'
                - $ref: '#/components/schemas/SearchResponse'
            application/xml:
              schema:
                type: string
                description: XML payload wrapped in `<lfm status="ok">…</lfm>`.
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '403':
          $ref: '#/components/responses/ErrorResponse'
        '429':
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: invokeWriteMethod
      summary: Invoke A Write Method
      description: 'Single write-side dispatch endpoint. Used for authenticated write actions:

        `track.scrobble`, `track.updateNowPlaying`, `track.love`, `track.unlove`,

        `album.addTags`, `album.removeTag`, `artist.addTags`, `artist.removeTag`,

        `track.addTags`, `track.removeTag`. POST body parameters are

        `application/x-www-form-urlencoded` UTF-8 encoded and must include

        `api_key`, `sk` (session key), and `api_sig`.

        '
      tags:
      - Album
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/WriteRequestBody'
      responses:
        '200':
          description: Successful write response with status wrapper.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WriteResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '403':
          $ref: '#/components/responses/ErrorResponse'
        '429':
          $ref: '#/components/responses/ErrorResponse'
  /?method=album.addTags:
    post:
      operationId: albumAddTags
      summary: Add Album Tags
      tags:
      - Album
      description: Tag an album using a list of user supplied tags. Requires authentication.
      requestBody:
        $ref: '#/components/requestBodies/AlbumTagWrite'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WriteResponse'
  /?method=album.getInfo:
    get:
      operationId: albumGetInfo
      summary: Get Album Info
      tags:
      - Album
      description: Get the metadata and tracklist for an album on Last.fm using the album name or a musicbrainz id.
      parameters:
      - $ref: '#/components/parameters/ApiKeyParam'
      - $ref: '#/components/parameters/FormatParam'
      - name: artist
        in: query
        schema:
          type: string
      - name: album
        in: query
        schema:
          type: string
      - name: mbid
        in: query
        schema:
          type: string
      - name: lang
        in: query
        schema:
          type: string
          example: en
      - name: autocorrect
        in: query
        schema:
          type: integer
          enum:
          - 0
          - 1
      - name: username
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Album info envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlbumInfoResponse'
  /?method=album.getTags:
    get:
      operationId: albumGetTags
      summary: Get Album Tags
      tags:
      - Album
      description: Get the tags applied by an individual user to an album on Last.fm.
      parameters:
      - $ref: '#/components/parameters/ApiKeyParam'
      - $ref: '#/components/parameters/FormatParam'
      - name: artist
        in: query
        schema:
          type: string
      - name: album
        in: query
        schema:
          type: string
      - name: mbid
        in: query
        schema:
          type: string
      - name: user
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: User tags applied to the album.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagListResponse'
  /?method=album.getTopTags:
    get:
      operationId: albumGetTopTags
      summary: Get Top Album Tags
      tags:
      - Album
      description: Get the top tags for an album on Last.fm, ordered by popularity.
      parameters:
      - $ref: '#/components/parameters/ApiKeyParam'
      - $ref: '#/components/parameters/FormatParam'
      - name: artist
        in: query
        schema:
          type: string
      - name: album
        in: query
        schema:
          type: string
      - name: mbid
        in: query
        schema:
          type: string
      - name: autocorrect
        in: query
        schema:
          type: integer
          enum:
          - 0
          - 1
      responses:
        '200':
          description: Top tags for the album.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopTagsResponse'
  /?method=album.removeTag:
    post:
      operationId: albumRemoveTag
      summary: Remove Album Tag
      tags:
      - Album
      description: Remove a user's tag from an album.
      requestBody:
        $ref: '#/components/requestBodies/AlbumTagWrite'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WriteResponse'
  /?method=album.search:
    get:
      operationId: albumSearch
      summary: Search Albums
      tags:
      - Album
      description: Search for an album by name. Returns album matches sorted by relevance.
      parameters:
      - $ref: '#/components/parameters/ApiKeyParam'
      - $ref: '#/components/parameters/FormatParam'
      - name: album
        in: query
        required: true
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
          default: 30
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      responses:
        '200':
          description: Search results for albums.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
components:
  responses:
    ErrorResponse:
      description: Error response (status='failed').
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorPayload'
        application/xml:
          schema:
            type: string
            description: '`<lfm status="failed"><error code="N">message</error></lfm>`'
  schemas:
    Artist:
      type: object
      properties:
        name:
          type: string
        mbid:
          type: string
        url:
          type: string
          format: uri
        image:
          type: array
          items:
            $ref: '#/components/schemas/Image'
        streamable:
          type: string
        ontour:
          type: string
        stats:
          type: object
          properties:
            listeners:
              type: string
            playcount:
              type: string
        similar:
          type: object
          properties:
            artist:
              type: array
              items:
                $ref: '#/components/schemas/Artist'
        tags:
          type: object
          properties:
            tag:
              type: array
              items:
                $ref: '#/components/schemas/Tag'
        bio:
          $ref: '#/components/schemas/Wiki'
    SearchResponse:
      type: object
      properties:
        results:
          type: object
          properties:
            opensearch:Query:
              type: object
              additionalProperties: true
            opensearch:totalResults:
              type: string
            opensearch:startIndex:
              type: string
            opensearch:itemsPerPage:
              type: string
            albummatches:
              type: object
              properties:
                album:
                  type: array
                  items:
                    $ref: '#/components/schemas/Album'
            artistmatches:
              type: object
              properties:
                artist:
                  type: array
                  items:
                    $ref: '#/components/schemas/Artist'
            trackmatches:
              type: object
              properties:
                track:
                  type: array
                  items:
                    $ref: '#/components/schemas/Track'
    Image:
      type: object
      properties:
        size:
          type: string
          enum:
          - small
          - medium
          - large
          - extralarge
          - mega
        '#text':
          type: string
          format: uri
    ChartResponse:
      type: object
      properties:
        artists:
          type: object
          properties:
            artist:
              type: array
              items:
                $ref: '#/components/schemas/Artist'
    AlbumInfoResponse:
      type: object
      properties:
        album:
          $ref: '#/components/schemas/Album'
    ArtistInfoResponse:
      type: object
      properties:
        artist:
          $ref: '#/components/schemas/Artist'
    TopTagsResponse:
      type: object
      properties:
        toptags:
          type: object
          properties:
            tag:
              type: array
              items:
                $ref: '#/components/schemas/Tag'
    Track:
      type: object
      properties:
        name:
          type: string
        mbid:
          type: string
        url:
          type: string
          format: uri
        duration:
          type: string
        artist:
          $ref: '#/components/schemas/Artist'
        album:
          type: object
          properties:
            artist:
              type: string
            title:
              type: string
            mbid:
              type: string
            url:
              type: string
              format: uri
        listeners:
          type: string
        playcount:
          type: string
        userplaycount:
          type: string
        userloved:
          type: string
          enum:
          - '0'
          - '1'
        toptags:
          type: object
          properties:
            tag:
              type: array
              items:
                $ref: '#/components/schemas/Tag'
        wiki:
          $ref: '#/components/schemas/Wiki'
        '@attr':
          type: object
          properties:
            nowplaying:
              type: string
        date:
          type: object
          properties:
            uts:
              type: string
            '#text':
              type: string
    WriteRequestBody:
      type: object
      required:
      - method
      - api_key
      properties:
        method:
          type: string
        api_key:
          type: string
        sk:
          type: string
          description: Session key returned by auth.getSession / auth.getMobileSession.
        api_sig:
          type: string
          description: MD5 signature of params + secret.
      additionalProperties: true
    TrackInfoResponse:
      type: object
      properties:
        track:
          $ref: '#/components/schemas/Track'
    Tag:
      type: object
      properties:
        name:
          type: string
        url:
          type: string
          format: uri
        count:
          type: integer
    UserProfile:
      type: object
      properties:
        name:
          type: string
        realname:
          type: string
        url:
          type: string
          format: uri
        country:
          type: string
        age:
          type: string
        gender:
          type: string
        subscriber:
          type: string
        playcount:
          type: string
        playlists:
          type: string
        bootstrap:
          type: string
        registered:
          type: object
          properties:
            unixtime:
              type: string
            '#text':
              type: string
        image:
          type: array
          items:
            $ref: '#/components/schemas/Image'
    TagListResponse:
      type: object
      properties:
        tags:
          type: object
          properties:
            tag:
              type: array
              items:
                $ref: '#/components/schemas/Tag'
    Wiki:
      type: object
      properties:
        published:
          type: string
        summary:
          type: string
        content:
          type: string
    GeoResponse:
      type: object
      properties:
        topartists:
          type: object
          properties:
            artist:
              type: array
              items:
                $ref: '#/components/schemas/Artist'
    Album:
      type: object
      properties:
        artist:
          type: string
        name:
          type: string
        mbid:
          type: string
        url:
          type: string
          format: uri
        image:
          type: array
          items:
            $ref: '#/components/schemas/Image'
        listeners:
          type: string
        playcount:
          type: string
        tracks:
          type: object
          properties:
            track:
              type: array
              items:
                $ref: '#/components/schemas/Track'
        tags:
          type: object
          properties:
            tag:
              type: array
              items:
                $ref: '#/components/schemas/Tag'
        wiki:
          $ref: '#/components/schemas/Wiki'
    UserInfoResponse:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/UserProfile'
    WriteResponse:
      type: object
      properties:
        status:
          type: string
          example: ok
    ErrorPayload:
      type: object
      properties:
        error:
          type: integer
          description: 'Numeric Last.fm error code. Common: 2 invalid service, 3 invalid method,

            4 authentication failed, 5 invalid format, 6 invalid parameters,

            7 invalid resource, 8 operation failed, 9 invalid session key,

            10 invalid api key, 11 service offline, 13 invalid method signature,

            16 service temporarily unavailable, 26 suspended api key, 29 rate limit exceeded.

            '
        message:
          type: string
    TagInfoResponse:
      type: object
      properties:
        tag:
          type: object
          properties:
            name:
              type: string
            total:
              type: integer
            reach:
              type: integer
            wiki:
              $ref: '#/components/schemas/Wiki'
  parameters:
    MethodParam:
      name: method
      in: query
      required: true
      schema:
        type: string
      description: 'Method name in `package.method` format (e.g. `track.getInfo`,

        `chart.getTopArtists`, `user.getRecentTracks`).

        '
    FormatParam:
      name: format
      in: query
      schema:
        type: string
        enum:
        - xml
        - json
        default: xml
      description: Response format. Defaults to XML.
    ApiKeyParam:
      name: api_key
      in: query
      required: true
      schema:
        type: string
      description: Your Last.fm API key.
    CallbackParam:
      name: callback
      in: query
      schema:
        type: string
      description: Optional JSONP callback function name when `format=json`.
  requestBodies:
    AlbumTagWrite:
      required: true
      content:
        application/x-www-form-urlencoded:
          schema:
            type: object
            required:
            - method
            - api_key
            - artist
            - album
            - tags
            - sk
            - api_sig
            properties:
              method:
                type: string
                enum:
                - album.addTags
                - album.removeTag
              api_key:
                type: string
              artist:
                type: string
              album:
                type: string
              tags:
                type: string
                description: Comma-separated tag list (max 10 for addTags).
              tag:
                type: string
                description: Single tag (for removeTag).
              sk:
                type: string
              api_sig:
                type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: api_key
      description: Required on all calls. Obtain from https://www.last.fm/api/account/create.
    SignedAuth:
      type: apiKey
      in: query
      name: api_sig
      description: 'MD5 signature of all request parameters (excluding format and callback)

        sorted alphabetically by name, concatenated as name+value pairs, with

        the shared secret appended. Required for all write/auth methods.

        '