Skip to main content

​
SpotifyTrack

Represents a Spotify track with complete metadata.
​
id
string
required
Unique Spotify identifier for the track
​
name
string
required
The name of the track
​
type
'track'
required
The object type, always set to ‘track’
​
artists
SpotifyArtist[]
required
Array of artists who performed the track
​
album
SpotifyAlbum
required
The album on which the track appears
​
available_markets
string[]
required
List of country codes where the track is available
​
disc_number
number
required
The disc number of the track (usually 1)
​
duration_ms
number
required
The track length in milliseconds
​
episode
boolean
required
Whether the track is an episode (podcast)
​
explicit
boolean
required
Whether the track has explicit content
​
href
string
required
Full Spotify API URL for the track
​
is_local
boolean
required
Whether the track is from a local file
​
preview_url
string | null
required
URL to a 30-second preview of the track, or null if not available
​
track
boolean
required
Whether the item is a track
​
track_number
number
required
The track number on the album
​
uri
string
required
Spotify URI for the track (spotify:track:…)
​
is_playable
boolean
Whether the track can be played in the current market

​
SpotifyArtist

Represents a Spotify artist.
​
id
string
required
Unique Spotify identifier for the artist
​
name
string
required
The name of the artist
​
type
'artist'
required
The object type, always set to ‘artist’
​
images
SpotifyImage[]
Array of artist images in various sizes

​
SpotifyAlbum

Represents a Spotify album.
​
id
string
required
Unique Spotify identifier for the album
​
name
string
required
The name of the album
​
type
'album'
required
The object type, always set to ‘album’
​
images
SpotifyImage[]
required
Array of album cover art in various sizes

​
SpotifyPlaylist

Represents a Spotify playlist.
​
id
string
required
Unique Spotify identifier for the playlist
​
name
string
required
The name of the playlist
​
type
'playlist'
required
The object type, always set to ‘playlist’
​
images
SpotifyImage[]
required
Array of playlist cover images in various sizes

​
SpotifyImage

Represents an image resource from Spotify.
​
url
string
required
The source URL of the image
​
height
number
required
The image height in pixels
​
width
number
required
The image width in pixels

​
SpotifyItem

Union type representing any Spotify item that can appear in search results or the queue. 
type SpotifyItem = SpotifyTrack | SpotifyArtist | SpotifyAlbum | SpotifyPlaylist;
This type is commonly used in search functionality where results can be of different types. Each item has a discriminated type field ('track', 'artist', 'album', or 'playlist') that allows for type narrowing.

​
Example Usage

function handleSearchResult(item: SpotifyItem) {
  switch (item.type) {
    case 'track':
      // TypeScript knows item is SpotifyTrack
      console.log(`Track: ${item.name} - ${item.artists[0].name}`);
      break;
    case 'artist':
      // TypeScript knows item is SpotifyArtist
      console.log(`Artist: ${item.name}`);
      break;
    case 'album':
      // TypeScript knows item is SpotifyAlbum
      console.log(`Album: ${item.name}`);
      break;
    case 'playlist':
      // TypeScript knows item is SpotifyPlaylist
      console.log(`Playlist: ${item.name}`);
      break;
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us