Package com.adamratzman.spotify.models

Types

AbstractPagingObject

common

abstract class AbstractPagingObject<T : Any, Z : AbstractPagingObject<T, Z>> : PagingObjectBase<T, Z> , List<T?>

The offset-based paging object is a container for a set of objects.

Album

common

data class Album(albumTypeString: String, availableMarketsString: List<String>, externalIdsString: Map<String, String>, externalUrlsString: Map<String, String>, href: String, id: String, uri: AlbumUri, artists: List<SimpleArtist>, copyrights: List<SpotifyCopyright>, genres: List<String>, images: List<SpotifyImage>, label: String, name: String, popularity: Int, releaseDateString: String, releaseDatePrecision: String, tracks: PagingObject<SimpleTrack>, type: String, totalTracks: Int, restrictions: Restrictions?) : CoreObject

Represents an Album on Spotify

AlbumResultType

common

enum AlbumResultType : Enum<AlbumResultType>

Album search type

AlbumUri

common

class AlbumUri(input: String) : ImmutableCollectionUri, ContextUri

Represents a Spotify Album URI (spotify:album:XXXXXXXXXX), parsed from either a Spotify ID or taken from an endpoint.

AlbumUriSerializer

common

object AlbumUriSerializer : KSerializer<AlbumUri>

Artist

common

data class Artist(externalUrlsString: Map<String, String>, href: String, id: String, uri: ArtistUri, followers: Followers, genres: List<String>, images: List<SpotifyImage>, name: String, popularity: Int, type: String) : CoreObject

Represents an Artist (distinct from a regular user) on Spotify

ArtistUri

common

class ArtistUri(input: String) : SpotifyUri, ContextUri

Represents a Spotify Artist URI (spotify:artist:XXXXXXXXXX), parsed from either a Spotify ID or taken from an endpoint.

ArtistUriSerializer

common

object ArtistUriSerializer : KSerializer<ArtistUri>

AudioAnalysis

common

data class AudioAnalysis(bars: List<TimeInterval>, beats: List<TimeInterval>, meta: AudioAnalysisMeta, sections: List<AudioSection>, segments: List<AudioSegment>, tatums: List<TimeInterval>, track: TrackAnalysis)

The Audio Analysis endpoint provides low-level audio analysis for all of the tracks in the Spotify catalog.

AudioAnalysisMeta

common

data class AudioAnalysisMeta(analyzerVersion: String, platform: String, detailedStatus: String, statusCode: Int?, timestamp: Long, analysisTime: Float, inputProcess: String)

Information about the analysis run

AudioFeatures

common

data class AudioFeatures(acousticness: Float, analysisUrl: String, danceability: Float, durationMs: Int, energy: Float, id: String, instrumentalness: Float, key: Int, liveness: Float, loudness: Float, mode: Int, speechiness: Float, tempo: Float, timeSignature: Int, trackHref: String, type: String, uri: PlayableUri, valence: Float)

General attributes of a Track

AudioSection

common

data class AudioSection(start: Float, duration: Float, confidence: Float, loudness: Float, tempo: Float?, tempoConfidence: Float?, key: Int, keyConfidence: Float?, mode: Int?, modeConfidence: Float?, timeSignature: Int, timeSignatureConfidence: Float)

Sections are defined by large variations in rhythm or timbre, e.g.

AudioSegment

common

data class AudioSegment(start: Float?, duration: Float, confidence: Float?, loudnessStart: Float, loudnessMaxTime: Float?, loudnessMax: Float, loudnessEnd: Float?, pitches: List<Float>, timbre: List<Float>)

Audio segments attempts to subdivide a song into many segments, with each segment containing a roughly consistent sound throughout its duration.

AuthenticationError

common

data class AuthenticationError(error: String, description: String)

An exception during the authentication process

CollectionUri

common

sealed class CollectionUri : SpotifyUri

Represents a Spotify Collection URI (one of PlaylistUri or ImmutableCollectionUri), parsed from either a Spotify ID or taken from an endpoint.

CollectionUriSerializer

common

object CollectionUriSerializer : KSerializer<CollectionUri>

ContextUri

common

interface ContextUri : ISpotifyUri

Represents a Spotify Context URI (one of AlbumUri, ArtistUri, PlaylistUri, or ShowUri),

ContextUriSerializer

common

object ContextUriSerializer : KSerializer<ContextUri>

CopyrightType

common

enum CopyrightType : Enum<CopyrightType> , ResultEnum

CoreObject

common

abstract class CoreObject : Identifiable

Represents a core Spotify object such as a Track or Album

CurrentlyPlayingContext

common

data class CurrentlyPlayingContext(timestamp: Long, device: Device, progressMs: Int?, isPlaying: Boolean, track: Track?, shuffleState: Boolean, repeatStateString: String, context: SpotifyContext?)

Information about the current playback

CurrentlyPlayingObject

common

data class CurrentlyPlayingObject(context: SpotifyContext?, timestamp: Long, progressMs: Int?, isPlaying: Boolean, track: Track?, currentlyPlayingTypeString: String, actions: PlaybackActions)

Information about the currently playing track and context

CurrentlyPlayingType

common

enum CurrentlyPlayingType : Enum<CurrentlyPlayingType> , ResultEnum

The object type of the currently playing item

Cursor

common

data class Cursor(before: String?, after: String?)

The cursor to use as key to find the next (or previous) page of items.

CursorBasedPagingObject

common

data class CursorBasedPagingObject<T : Any>(href: String, items: List<T>, limit: Int, next: String?, cursor: Cursor?, total: Int, offset: Int, previous: String?) : PagingObjectBase<T, CursorBasedPagingObject<T>>

The cursor-based paging object is a container for a set of objects.

Device

common

data class Device(id: String?, isActive: Boolean, isPrivateSession: Boolean, isRestricted: Boolean, name: String, typeString: String, volumePercent: Int) : IdentifiableNullable

A device which is connected to the Spotify user

DeviceType

common

enum DeviceType : Enum<DeviceType>

Electronic type of registered Spotify device

DisallowablePlaybackAction

common

data class DisallowablePlaybackAction(action: PlaybackAction, disallowed: Boolean)

Maps a playback action to whether the user is disallowed from doing it

Episode

common

data class Episode(audioPreviewUrl: String?, description: String?, durationMs: Int, explicit: Boolean, externalUrlsString: Map<String, String>, href: String, id: String, images: List<SpotifyImage>, isExternallyHosted: Boolean, isPlayable: Boolean, language: String?, showLanguagesPrivate: List<String>, name: String, releaseDateString: String, releaseDatePrecisionString: String, resumePoint: ResumePoint?, show: SimpleShow, type: String, uri: EpisodeUri) : CoreObject

An episode (podcast) on Spotify

EpisodeUri

common

class EpisodeUri(input: String) : PlayableUri

Represents a Spotify Episode URI (spotify:episode:XXXXXXXXXX), parsed from either a Spotify ID or taken from an endpoint.

EpisodeUriSerializer

common

object EpisodeUriSerializer : KSerializer<EpisodeUri>

ErrorObject

common

data class ErrorObject(status: Int, message: String, reason: String?)

An endpoint exception from Spotify

ErrorResponse

common

data class ErrorResponse(error: ErrorObject, exception: Exception?)

Wraps around ErrorObject.

ExplicitContentSettings

common

data class ExplicitContentSettings(filterEnabled: Boolean, filterLocked: Boolean)

ExternalId

common

class ExternalId(key: String, id: String)

An external id linked to the result object

ExternalUrl

common

class ExternalUrl(name: String, url: String)

Key/value pair mapping a name to an arbitrary url

FeaturedPlaylists

common

data class FeaturedPlaylists(message: String, playlists: PagingObject<SimplePlaylist>)

Spotify featured playlists (on the Browse tab)

Followers

common

data class Followers(href: String?, total: Int?)

Information about a Spotify user's followers

Identifiable

common

abstract class Identifiable : IdentifiableNullable

Represents an identifiable Spotify object such as an Album or Recommendation Seed

IdentifiableNullable

common

abstract class IdentifiableNullable : NeedsApi

Represents an identifiable Spotify object such as an Album or Recommendation Seed

ImmutableCollectionUri

common

sealed class ImmutableCollectionUri : CollectionUri

Represents a Spotify Immutable Collection URI (one of AlbumUri or ShowUri), parsed from either a Spotify ID or taken from an endpoint.

ImmutableCollectionUriSerializer

common

object ImmutableCollectionUriSerializer : KSerializer<ImmutableCollectionUri>

ISpotifyUri

common

interface ISpotifyUri

LinkedTrack

common

data class LinkedTrack(externalUrlsString: Map<String, String>, href: String, id: String, uri: PlayableUri, type: String) : CoreObject

Represents a relinked track.

LocalTrack

common

data class LocalTrack(album: SimpleLocalAlbum, artists: List<SimpleLocalArtist>, href: String?, id: String?, discNumber: String?, durationMs: Int?, explicit: Boolean?, isLocal: Boolean, name: String, popularity: Int?, trackNumber: Int?, type: String, uri: LocalTrackUri) : IdentifiableNullable, Playable

Local track object that representing a song uploaded from a client locally

LocalTrackUri

common

class LocalTrackUri(input: String) : PlayableUri

Represents a Spotify Local Track URI (spotify:local:XXXXXXXXXX), parsed from either a Spotify ID or taken from an endpoint.

LocalTrackUriSerializer

common

object LocalTrackUriSerializer : KSerializer<LocalTrackUri>

NeedsApi

common

abstract class NeedsApi

Provide access to the underlying SpotifyApi

NullablePagingObject

common

class NullablePagingObject<T : Any>(href: String, items: List<T?>, limit: Int, next: String?, offset: Int, previous: String?, total: Int) : AbstractPagingObject<T, NullablePagingObject<T>>

The offset-based nullable paging object is a container for a set of objects.

PagingObject

common

data class PagingObject<T : Any>(href: String, items: List<T>, limit: Int, next: String?, offset: Int, previous: String?, total: Int) : AbstractPagingObject<T, PagingObject<T>>

The offset-based non-nullable paging object is a container for a set of objects.

PagingObjectBase

common

abstract class PagingObjectBase<T : Any, Z : PagingObjectBase<T, Z>> : NeedsApi, List<T?>

PagingTraversalType

common

enum PagingTraversalType : Enum<PagingTraversalType>

Playable

common

interface Playable

A local track, episode, or track.

PlayableSerializer

common

object PlayableSerializer : KSerializer<Playable>

PlayableUri

common

sealed class PlayableUri : SpotifyUri

Represents a Spotify Playable URI (one of SpotifyTrackUri, LocalTrackUri, or EpisodeUri), parsed from either a Spotify ID or taken from an endpoint.

PlayableUriSerializer

common

object PlayableUriSerializer : KSerializer<PlayableUri>

PlaybackAction

common

enum PlaybackAction : Enum<PlaybackAction> , ResultEnum

Action a user takes that will affect current playback

PlaybackActions

common

data class PlaybackActions(disallowsString: Map<String, Boolean?>)

List of playback actions (pause, resume, etc) which a user is disallowed or allowed to do.

PlayHistory

common

data class PlayHistory(track: SimpleTrack, playedAt: String, context: SpotifyContext?)

Information about a previously-played track

Playlist

common

data class Playlist(externalUrlsString: Map<String, String>, href: String, id: String, uri: PlaylistUri, collaborative: Boolean, description: String?, followers: Followers, primaryColor: String?, images: List<SpotifyImage>, name: String, owner: SpotifyPublicUser, public: Boolean?, snapshotIdString: String, tracks: PagingObject<PlaylistTrack>, type: String) : CoreObject

Represents a Playlist on Spotify

PlaylistTrack

common

data class PlaylistTrack(primaryColor: String?, addedAt: String?, addedBy: SpotifyPublicUser?, isLocal: Boolean?, track: Playable?, videoThumbnail: VideoThumbnail?)

Represents a Spotify track inside a Playlist

PlaylistTrackInfo

common

data class PlaylistTrackInfo(href: String, total: Int)

A collection containing a link ( href ) to the Web API endpoint where full details of the playlist’s tracks can be retrieved, along with the total number of tracks in the playlist.

PlaylistUri

common

class PlaylistUri(input: String) : CollectionUri, ContextUri

Represents a Spotify Playlist URI (spotify:playlist:XXXXXXXXXX), parsed from either a Spotify ID or taken from an endpoint.

PlaylistUriSerializer

common

object PlaylistUriSerializer : KSerializer<PlaylistUri>

PodcastEpisodeTrack

common

data class PodcastEpisodeTrack(album: SimpleAlbum, artists: List<SimpleArtist>, availableMarketsString: List<String>, discNumber: Int, durationMs: Int, episode: Boolean?, explicit: Boolean, externalUrlsString: Map<String, String>, externalIdsString: Map<String, String>, href: String, id: String, isLocal: Boolean?, isPlayable: Boolean, name: String, popularity: Int, previewUrl: String?, track: Boolean?, trackNumber: Int, type: String, uri: PlayableUri, linkedTrack: LinkedTrack?) : RelinkingAvailableResponse, Playable

An episode (podcast) on Spotify

RecommendationResponse

common

data class RecommendationResponse(seeds: List<RecommendationSeed>, tracks: List<Track>)

RecommendationSeed

common

data class RecommendationSeed(href: String?, id: String, initialPoolSize: Int, afterFilteringSize: Int, afterRelinkingSize: Int?, type: String) : Identifiable

Seed from which the recommendation was constructed

ReleaseDate

common

data class ReleaseDate(year: Int, month: Int?, day: Int?)

RelinkingAvailableResponse

common

abstract class RelinkingAvailableResponse : CoreObject

Represents a response for which a relinked track could be available

Restrictions

common

data class Restrictions(reason: String)

Contains an explanation of why a track is not available

ResultEnum

common

interface ResultEnum

Interface that allows easy identifier retrieval for children with an implemented identifier

ResumePoint

common

data class ResumePoint(fullyPlayed: Boolean, resumePositionMs: Int)

Represents the user’s most recent position in the episode.

SavedAlbum

common

data class SavedAlbum(addedAt: String, album: Album)

Represents an album saved in a user's library

SavedEpisode

common

data class SavedEpisode(addedAt: String, episode: Episode)

Represents an episode saved in a user's library

SavedShow

common

data class SavedShow(addedAt: String, show: SimpleShow)

Represents a show saved in a user's library

SavedTrack

common

data class SavedTrack(addedAt: String, track: Track)

Represents a track saved in a user's library

Show

common

data class Show(availableMarketsString: List<String>, copyrights: List<SpotifyCopyright>, description: String?, explicit: Boolean, episodes: NullablePagingObject<SimpleEpisode>, externalUrlsString: Map<String, String>, href: String, id: String, images: List<SpotifyImage>, isExternallyHosted: Boolean?, languagesString: List<String>, mediaType: String, name: String, publisher: String, type: String, uri: ShowUri) : CoreObject

Information about a Spotify show, including its episodes

ShowUri

common

class ShowUri(input: String) : ImmutableCollectionUri, ContextUri

Represents a Spotify Show URI (spotify:show:XXXXXXXXXX), parsed from either a Spotify ID or taken from an endpoint.

ShowUriSerializer

common

object ShowUriSerializer : KSerializer<ShowUri>

SimpleAlbum

common

data class SimpleAlbum(albumTypeString: String, availableMarketsString: List<String>, externalUrlsString: Map<String, String>, href: String, id: String, uri: SpotifyUri, artists: List<SimpleArtist>, images: List<SpotifyImage>, name: String, type: String, restrictions: Restrictions?, releaseDateString: String, releaseDatePrecisionString: String, totalTracks: Int?, albumGroupString: String?) : CoreObject

Simplified Album object that can be used to retrieve a full Album

SimpleArtist

common

data class SimpleArtist(externalUrlsString: Map<String, String>, href: String, id: String, uri: SpotifyUri, name: String, type: String) : CoreObject

Simplified Artist object that can be used to retrieve a full Artist

SimpleEpisode

common

data class SimpleEpisode(audioPreviewUrl: String?, description: String?, durationMs: Int, explicit: Boolean, externalUrlsString: Map<String, String>, href: String, id: String, images: List<SpotifyImage>, isExternallyHosted: Boolean, isPlayable: Boolean, language: String?, showLanguagesPrivate: List<String>, name: String, releaseDateString: String, releaseDatePrecisionString: String, resumePoint: ResumePoint?, type: String, uri: SpotifyUri) : CoreObject

A simplified episode (podcast) on Spotify

SimpleLocalAlbum

common

data class SimpleLocalAlbum(albumType: String?, artists: List<SimpleLocalArtist>, name: String, releaseDate: String?, releaseDatePrecision: String?, type: String)

Local album object that goes with LocalTrack - represents the local album it was obtained from (likely "Local Files")

SimpleLocalArtist

common

data class SimpleLocalArtist(name: String, type: String)

Local artist object (goes with LocalTrack) representing an artist on a local track

SimplePlaylist

common

data class SimplePlaylist(externalUrlsString: Map<String, String>, href: String, id: String, uri: SpotifyUri, collaborative: Boolean, images: List<SpotifyImage>, name: String, description: String?, owner: SpotifyPublicUser, primaryColor: String?, public: Boolean?, snapshotIdString: String, tracks: PlaylistTrackInfo, type: String) : CoreObject

Simplified Playlist object that can be used to retrieve a full Playlist

SimpleShow

common

data class SimpleShow(availableMarketsString: List<String>, externalUrlsString: Map<String, String>, copyrights: List<SpotifyCopyright>, description: String?, explicit: Boolean, href: String, id: String, images: List<SpotifyImage>, isExternallyHosted: Boolean?, languagesString: List<String>, mediaType: String, name: String, publisher: String, type: String, uri: SpotifyUri) : CoreObject

Basic information about a Spotify show

SimpleTrack

common

data class SimpleTrack(externalUrlsString: Map<String, String>, availableMarketsString: List<String>, externalIdsString: Map<String, String>, href: String, id: String, uri: SpotifyUri, artists: List<SimpleArtist>, discNumber: Int, durationMs: Int, explicit: Boolean, isPlayable: Boolean, linkedTrack: LinkedTrack?, name: String, previewUrl: String?, trackNumber: Int, type: String, isLocal: Boolean?, popularity: Int?, restrictions: Restrictions?) : RelinkingAvailableResponse

Simplified Playlist object that can be used to retrieve a full Playlist

SpotifyCategory

common

data class SpotifyCategory(href: String, id: String, icons: List<SpotifyImage>, name: String) : Identifiable

Spotify music category

SpotifyContext

common

data class SpotifyContext(externalUrlsString: Map<String, String>, href: String, uri: ContextUri, typeString: String)

Context in which a track was played

SpotifyContextType

common

enum SpotifyContextType : Enum<SpotifyContextType> , ResultEnum

SpotifyCopyright

common

data class SpotifyCopyright(textString: String, typeString: String)

Describes an album's copyright information

SpotifyImage

common

data class SpotifyImage(height: Int?, url: String, width: Int?)

A Spotify image

SpotifyPublicUser

common

data class SpotifyPublicUser(externalUrlsString: Map<String, String>, href: String, id: String, uri: UserUri, displayName: String?, followers: Followers, images: List<SpotifyImage>, type: String) : CoreObject

Public information about a Spotify user

SpotifyRatelimitedException

common

class SpotifyRatelimitedException(time: Long) : SpotifyException.UnNullableException

Thrown when SpotifyApiOptions.retryWhenRateLimited is false and requests have been ratelimited

SpotifySearchResult

common

data class SpotifySearchResult(albums: PagingObject<SimpleAlbum>?, artists: PagingObject<Artist>?, playlists: PagingObject<SimplePlaylist>?, tracks: PagingObject<Track>?, episodes: NullablePagingObject<SimpleEpisode>?, shows: NullablePagingObject<SimpleShow>?)

SpotifyTrackUri

common

class SpotifyTrackUri(input: String) : PlayableUri

Represents a Spotify Track URI (spotify:track:XXXXXXXXXX), parsed from either a Spotify ID or taken from an endpoint.

SpotifyTrackUriSerializer

common

object SpotifyTrackUriSerializer : KSerializer<SpotifyTrackUri>

SpotifyUri

common

sealed class SpotifyUri : ISpotifyUri

Represents any Spotify URI (one of ArtistUri, PlayableUri, ImmutableCollectionUri, UserUri, PlaylistUri), parsed from either a Spotify ID or taken from an endpoint.

SpotifyUriException

common

class SpotifyUriException(message: String) : SpotifyException.BadRequestException

Exception instantiating or deserializing a uri perceived as invalid

SpotifyUriSerializer

common

object SpotifyUriSerializer : KSerializer<SpotifyUri>

SpotifyUserInformation

common

data class SpotifyUserInformation(externalUrlsString: Map<String, String>, href: String, id: String, uri: UserUri, country: String?, displayName: String?, email: String?, followers: Followers, images: List<SpotifyImage>, product: String?, explicitContentSettings: ExplicitContentSettings?, type: String) : CoreObject

Private information about a Spotify user.

TimeInterval

common

data class TimeInterval(start: Float, duration: Float, confidence: Float)

This is a generic object used to represent various time intervals within Audio Analysis.

Token

common

data class Token(accessToken: String, tokenType: String, expiresIn: Int, refreshToken: String?, scopeString: String?)

Represents a Spotify Token, retrieved through instantiating a SpotifyApi

TokenValidityResponse

common

data class TokenValidityResponse(isValid: Boolean, exception: Exception?)

Track

common

data class Track(externalUrlsString: Map<String, String>, externalIdsString: Map<String, String>, availableMarketsString: List<String>, href: String, id: String, uri: PlayableUri, album: SimpleAlbum, artists: List<SimpleArtist>, isPlayable: Boolean, discNumber: Int, durationMs: Int, explicit: Boolean, linkedTrack: LinkedTrack?, name: String, popularity: Int, previewUrl: String?, trackNumber: Int, type: String, isLocal: Boolean?, restrictions: Restrictions?, episode: Boolean?, track: Boolean?) : RelinkingAvailableResponse, Playable

Represents a music track on Spotify

TrackAnalysis

common

data class TrackAnalysis(numSamples: Int, duration: Float, sampleMd5: String?, offsetSeconds: Int?, windowSeconds: Int?, analysisSampleRate: Float, analysisChannels: Int, endOfFadeIn: Float, startOfFadeOut: Float, loudness: Float, tempo: Float, tempoConfidence: Float, timeSignature: Int, timeSignatureConfidence: Float, key: Int, keyConfidence: Float, mode: Int?, modeConfidence: Float, codestring: String, codeVersion: Float, echoprintstring: String, echoprintVersion: Float, synchstring: String, synchVersion: Float, rhythmstring: String, rhythmVersion: Float)

General information about the track as a whole

UserUri

common

class UserUri(input: String) : SpotifyUri

Represents a Spotify User URI (spotify:user:XXXXXXXXXX), parsed from either a Spotify ID or taken from an endpoint.

UserUriSerializer

common

object UserUriSerializer : KSerializer<UserUri>

VideoThumbnail

common

data class VideoThumbnail(url: String?)