openapi: 3.0.3
info:
  title: Last.fm Web Services API (2.0) Album Track 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: Track
  description: Track metadata, scrobbling, love/unlove, tagging, 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:
      - Track
      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:
      - Track
      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=track.addTags:
    post:
      operationId: trackAddTags
      summary: Add Track Tags
      tags:
      - Track
      description: Tag a track using a list of user supplied tags.
      requestBody:
        $ref: '#/components/requestBodies/TrackTagWrite'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WriteResponse'
  /?method=track.getCorrection:
    get:
      operationId: trackGetCorrection
      summary: Get Track Correction
      tags:
      - Track
      description: Use the last.fm corrections data to check whether the supplied track has a correction to a canonical track.
      parameters:
      - $ref: '#/components/parameters/ApiKeyParam'
      - $ref: '#/components/parameters/FormatParam'
      - name: artist
        in: query
        required: true
        schema:
          type: string
      - name: track
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Suggested track correction.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /?method=track.getInfo:
    get:
      operationId: trackGetInfo
      summary: Get Track Info
      tags:
      - Track
      description: Get the metadata for a track on Last.fm using the artist/track name or a musicbrainz id.
      parameters:
      - $ref: '#/components/parameters/ApiKeyParam'
      - $ref: '#/components/parameters/FormatParam'
      - name: artist
        in: query
        schema:
          type: string
      - name: track
        in: query
        schema:
          type: string
      - name: mbid
        in: query
        schema:
          type: string
      - name: autocorrect
        in: query
        schema:
          type: integer
          enum:
          - 0
          - 1
      - name: username
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Track info envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackInfoResponse'
  /?method=track.getSimilar:
    get:
      operationId: trackGetSimilar
      summary: Get Similar Tracks
      tags:
      - Track
      description: Get the similar tracks for this track on Last.fm, based on listening data.
      parameters:
      - $ref: '#/components/parameters/ApiKeyParam'
      - $ref: '#/components/parameters/FormatParam'
      - name: artist
        in: query
        schema:
          type: string
      - name: track
        in: query
        schema:
          type: string
      - name: mbid
        in: query
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
          default: 100
      - name: autocorrect
        in: query
        schema:
          type: integer
          enum:
          - 0
          - 1
      responses:
        '200':
          description: Similar tracks list.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /?method=track.getTags:
    get:
      operationId: trackGetTags
      summary: Get Track Tags
      tags:
      - Track
      description: Get the tags applied by an individual user to a track on Last.fm.
      parameters:
      - $ref: '#/components/parameters/ApiKeyParam'
      - $ref: '#/components/parameters/FormatParam'
      - name: artist
        in: query
        schema:
          type: string
      - name: track
        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 for the track.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagListResponse'
  /?method=track.getTopTags:
    get:
      operationId: trackGetTopTags
      summary: Get Top Track Tags
      tags:
      - Track
      description: Get the top tags for this track on Last.fm, ordered by tag count.
      parameters:
      - $ref: '#/components/parameters/ApiKeyParam'
      - $ref: '#/components/parameters/FormatParam'
      - name: artist
        in: query
        schema:
          type: string
      - name: track
        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 track.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopTagsResponse'
  /?method=track.love:
    post:
      operationId: trackLove
      summary: Love Track
      tags:
      - Track
      description: Love a track for a user profile.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - method
              - api_key
              - artist
              - track
              - sk
              - api_sig
              properties:
                method:
                  type: string
                  enum:
                  - track.love
                api_key:
                  type: string
                artist:
                  type: string
                track:
                  type: string
                sk:
                  type: string
                api_sig:
                  type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WriteResponse'
  /?method=track.removeTag:
    post:
      operationId: trackRemoveTag
      summary: Remove Track Tag
      tags:
      - Track
      description: Remove a user's tag from a track.
      requestBody:
        $ref: '#/components/requestBodies/TrackTagWrite'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WriteResponse'
  /?method=track.scrobble:
    post:
      operationId: trackScrobble
      summary: Scrobble Track
      tags:
      - Track
      description: 'Add a track-play to a user''s profile (Scrobbling 2.0). Up to 50 scrobbles

        may be sent in a single batch using array notation

        (`artist[0]`, `track[0]`, `timestamp[0]` etc.). A track must be longer

        than 30 seconds and listened to for at least half its duration or 4 minutes

        (whichever comes first).

        '
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - method
              - api_key
              - artist
              - track
              - timestamp
              - sk
              - api_sig
              properties:
                method:
                  type: string
                  enum:
                  - track.scrobble
                api_key:
                  type: string
                artist:
                  type: string
                  description: Artist name. Use array notation (artist[i]) for batch.
                track:
                  type: string
                  description: Track name. Use array notation (track[i]) for batch.
                album:
                  type: string
                timestamp:
                  type: integer
                  description: Unix timestamp when track started. Use array notation for batch.
                albumArtist:
                  type: string
                trackNumber:
                  type: integer
                duration:
                  type: integer
                  description: Track length in seconds.
                mbid:
                  type: string
                streamId:
                  type: string
                chosenByUser:
                  type: integer
                  enum:
                  - 0
                  - 1
                context:
                  type: string
                sk:
                  type: string
                api_sig:
                  type: string
      responses:
        '200':
          description: Scrobble acceptance with per-scrobble status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScrobbleResponse'
  /?method=track.search:
    get:
      operationId: trackSearch
      summary: Search Tracks
      tags:
      - Track
      description: Search for a track by name. Returns track matches sorted by relevance.
      parameters:
      - $ref: '#/components/parameters/ApiKeyParam'
      - $ref: '#/components/parameters/FormatParam'
      - name: track
        in: query
        required: true
        schema:
          type: string
      - name: artist
        in: query
        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 tracks.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
  /?method=track.unlove:
    post:
      operationId: trackUnlove
      summary: Unlove Track
      tags:
      - Track
      description: UnLove a track for a user profile.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - method
              - api_key
              - artist
              - track
              - sk
              - api_sig
              properties:
                method:
                  type: string
                  enum:
                  - track.unlove
                api_key:
                  type: string
                artist:
                  type: string
                track:
                  type: string
                sk:
                  type: string
                api_sig:
                  type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WriteResponse'
  /?method=track.updateNowPlaying:
    post:
      operationId: trackUpdateNowPlaying
      summary: Update Now Playing
      tags:
      - Track
      description: Used to notify Last.fm that a user has started listening to a track.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - method
              - api_key
              - artist
              - track
              - sk
              - api_sig
              properties:
                method:
                  type: string
                  enum:
                  - track.updateNowPlaying
                api_key:
                  type: string
                artist:
                  type: string
                track:
                  type: string
                album:
                  type: string
                albumArtist:
                  type: string
                trackNumber:
                  type: integer
                context:
                  type: string
                duration:
                  type: integer
                mbid:
                  type: string
                sk:
                  type: string
                api_sig:
                  type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WriteResponse'
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'
    ScrobbleResponse:
      type: object
      properties:
        scrobbles:
          type: object
          properties:
            '@attr':
              type: object
              properties:
                accepted:
                  type: integer
                ignored:
                  type: integer
            scrobble:
              type: array
              items:
                type: object
                properties:
                  artist:
                    type: object
                    properties:
                      '#text':
                        type: string
                      corrected:
                        type: string
                  album:
                    type: object
                    properties:
                      '#text':
                        type: string
                      corrected:
                        type: string
                  track:
                    type: object
                    properties:
                      '#text':
                        type: string
                      corrected:
                        type: string
                  timestamp:
                    type: string
                  ignoredMessage:
                    type: object
                    properties:
                      code:
                        type: string
                      '#text':
                        type: string
    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'
    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'
    Tag:
      type: object
      properties:
        name:
          type: string
        url:
          type: string
          format: uri
        count:
          type: integer
    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:
    TrackTagWrite:
      required: true
      content:
        application/x-www-form-urlencoded:
          schema:
            type: object
            required:
            - method
            - api_key
            - artist
            - track
            - sk
            - api_sig
            properties:
              method:
                type: string
                enum:
                - track.addTags
                - track.removeTag
              api_key:
                type: string
              artist:
                type: string
              track:
                type: string
              tags:
                type: string
              tag:
                type: string
              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.

        '