API Reference

Last.fm Endpoints

Base URL: https://ws.audioscrobbler.com/2.0/

All requests require &format=json and &api_key={LASTFM_API_KEY}.

geo.getTopTracks

Returns the top tracks for a given country.

GET /?method=geo.getTopTracks&country={country}&api_key={key}&format=json&limit=20

Response shape used:

{
  tracks: {
    track: Track[]
  }
}

Track type:

interface Track {
  name: string
  artist: { name: string }
  listeners: string          // numeric string
  image: Image[]
  url: string
}

geo.getTopArtists

Returns the top artists for a given country.

GET /?method=geo.getTopArtists&country={country}&api_key={key}&format=json&limit=10

Response shape used:

{
  topartists: {
    artist: Artist[]
  }
}

Artist type:

interface Artist {
  name: string
  listeners: string          // numeric string
  image: Image[]
  url: string
}

artist.getInfo

Returns metadata and bio for a named artist.

GET /?method=artist.getInfo&artist={name}&api_key={key}&format=json&lang={locale}

Response shape used:

{
  artist: {
    name: string
    listeners: string
    playcount: string
    url: string
    image: Image[]
    bio: { summary: string; content: string }
    similar: { artist: SimilarArtist[] }
    tags: { tag: Tag[] }
  }
}

artist.getTopTracks

Returns the most-played tracks for a named artist.

GET /?method=artist.getTopTracks&artist={name}&api_key={key}&format=json&limit=10

Response shape used:

{
  toptracks: {
    track: Track[]   // Track.listeners may be absent; playcount is present instead
  }
}

Shared types

interface Image {
  '#text': string   // image URL (empty string when unavailable)
  size: 'small' | 'medium' | 'large' | 'extralarge'
}

Error responses

Last.fm returns HTTP 200 even on errors. The app checks for the error field:

{ error: number; message: string }

Common error codes:

App Routes

Supported locales: en, es, no, it

Supported countries ([country] slug):

Environment Variables

Set in .env.local for local development:

LASTFM_API_KEY=your_api_key_here

Set in Vercel Dashboard → Project → Settings → Environment Variables for production.