openapi: 3.0.3
info:
title: Last.fm Web Services API (2.0) Album Artist 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: Artist
description: Artist metadata, similarity, tagging, top albums/tracks, 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:
- Artist
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:
- Artist
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=artist.addTags:
post:
operationId: artistAddTags
summary: Add Artist Tags
tags:
- Artist
description: Tag an artist with one or more user supplied tags.
requestBody:
$ref: '#/components/requestBodies/ArtistTagWrite'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/WriteResponse'
/?method=artist.getCorrection:
get:
operationId: artistGetCorrection
summary: Get Artist Correction
tags:
- Artist
description: Use the last.fm corrections data to check whether the supplied artist has a correction to a canonical artist.
parameters:
- $ref: '#/components/parameters/ApiKeyParam'
- $ref: '#/components/parameters/FormatParam'
- name: artist
in: query
required: true
schema:
type: string
responses:
'200':
description: Suggested artist correction, if any.
content:
application/json:
schema:
type: object
additionalProperties: true
/?method=artist.getInfo:
get:
operationId: artistGetInfo
summary: Get Artist Info
tags:
- Artist
description: Get the metadata for an artist. Includes biography, listener counts, similar artists, tags.
parameters:
- $ref: '#/components/parameters/ApiKeyParam'
- $ref: '#/components/parameters/FormatParam'
- name: artist
in: query
schema:
type: string
- name: mbid
in: query
schema:
type: string
- name: lang
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: Artist info envelope.
content:
application/json:
schema:
$ref: '#/components/schemas/ArtistInfoResponse'
/?method=artist.getSimilar:
get:
operationId: artistGetSimilar
summary: Get Similar Artists
tags:
- Artist
description: Get all the artists similar to this artist.
parameters:
- $ref: '#/components/parameters/ApiKeyParam'
- $ref: '#/components/parameters/FormatParam'
- name: artist
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 artists list.
content:
application/json:
schema:
type: object
additionalProperties: true
/?method=artist.getTags:
get:
operationId: artistGetTags
summary: Get Artist Tags
tags:
- Artist
description: Get the tags applied by an individual user to an artist on Last.fm.
parameters:
- $ref: '#/components/parameters/ApiKeyParam'
- $ref: '#/components/parameters/FormatParam'
- name: artist
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 artist.
content:
application/json:
schema:
$ref: '#/components/schemas/TagListResponse'
/?method=artist.getTopAlbums:
get:
operationId: artistGetTopAlbums
summary: Get Top Albums For Artist
tags:
- Artist
description: Get the top albums for an artist on Last.fm, ordered by popularity.
parameters:
- $ref: '#/components/parameters/ApiKeyParam'
- $ref: '#/components/parameters/FormatParam'
- name: artist
in: query
schema:
type: string
- name: mbid
in: query
schema:
type: string
- name: limit
in: query
schema:
type: integer
default: 50
- name: page
in: query
schema:
type: integer
default: 1
- name: autocorrect
in: query
schema:
type: integer
enum:
- 0
- 1
responses:
'200':
description: Top albums for the artist.
content:
application/json:
schema:
$ref: '#/components/schemas/TopAlbumsResponse'
/?method=artist.getTopTags:
get:
operationId: artistGetTopTags
summary: Get Top Artist Tags
tags:
- Artist
description: Get the top tags for an artist on Last.fm, ordered by popularity.
parameters:
- $ref: '#/components/parameters/ApiKeyParam'
- $ref: '#/components/parameters/FormatParam'
- name: artist
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 artist.
content:
application/json:
schema:
$ref: '#/components/schemas/TopTagsResponse'
/?method=artist.getTopTracks:
get:
operationId: artistGetTopTracks
summary: Get Top Tracks For Artist
tags:
- Artist
description: Get the top tracks by an artist on Last.fm, ordered by popularity.
parameters:
- $ref: '#/components/parameters/ApiKeyParam'
- $ref: '#/components/parameters/FormatParam'
- name: artist
in: query
schema:
type: string
- name: mbid
in: query
schema:
type: string
- name: limit
in: query
schema:
type: integer
default: 50
- name: page
in: query
schema:
type: integer
default: 1
- name: autocorrect
in: query
schema:
type: integer
enum:
- 0
- 1
responses:
'200':
description: Top tracks for the artist.
content:
application/json:
schema:
$ref: '#/components/schemas/TopTracksResponse'
/?method=artist.removeTag:
post:
operationId: artistRemoveTag
summary: Remove Artist Tag
tags:
- Artist
description: Remove a user's tag from an artist.
requestBody:
$ref: '#/components/requestBodies/ArtistTagWrite'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/WriteResponse'
/?method=artist.search:
get:
operationId: artistSearch
summary: Search Artists
tags:
- Artist
description: Search for an artist by name. Returns artist matches sorted by relevance.
parameters:
- $ref: '#/components/parameters/ApiKeyParam'
- $ref: '#/components/parameters/FormatParam'
- name: artist
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 artists.
content:
application/json:
schema:
$ref: '#/components/schemas/SearchResponse'
components:
schemas:
TopTracksResponse:
type: object
properties:
toptracks:
type: object
properties:
track:
type: array
items:
$ref: '#/components/schemas/Track'
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'
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'
TopAlbumsResponse:
type: object
properties:
topalbums:
type: object
properties:
album:
type: array
items:
$ref: '#/components/schemas/Album'
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'
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>`'
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:
ArtistTagWrite:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- method
- api_key
- artist
- sk
- api_sig
properties:
method:
type: string
enum:
- artist.addTags
- artist.removeTag
api_key:
type: string
artist:
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.
'