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.
'