Package se.michaelthelin.spotify

Class SpotifyApi

java.lang.Object

se.michaelthelin.spotify.SpotifyApi

public class SpotifyApi
extends Object

Instances of the SpotifyApi class provide access to the Spotify Web API.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	SpotifyApi.Builder	Builder class for building SpotifyApi instances.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	DEFAULT_AUTHENTICATION_HOST	The default authentication host of Spotify API calls.
static final int	DEFAULT_AUTHENTICATION_PORT	The default authentication port of Spotify API calls.
static final String	DEFAULT_AUTHENTICATION_SCHEME	The default authentication http scheme of Spotify API calls.
static final String	DEFAULT_HOST	The default host of Spotify API calls.
static final IHttpManager	DEFAULT_HTTP_MANAGER	A HttpManager configured with default settings.
static final int	DEFAULT_PORT	The default port of Spotify API calls.
static final String	DEFAULT_SCHEME	The default http scheme of Spotify API calls.
static final Logger	LOGGER

Method Summary

Modifier and Type	Method	Description
AddItemsToPlaylistRequest.Builder	addItemsToPlaylist(String playlist_id, com.google.gson.JsonArray uris)	Add items to a playlist.
AddItemsToPlaylistRequest.Builder	addItemsToPlaylist(String playlist_id, String[] uris)	Add items to a playlist.
AddItemToUsersPlaybackQueueRequest.Builder	addItemToUsersPlaybackQueue(String uri)	Add a track or an episode to the end of the user's current playback queue.
AuthorizationCodeRequest.Builder	authorizationCode(String code)	Returns a builder that can be used to build requests for authorization code grants.
AuthorizationCodeRequest.Builder	authorizationCode(String client_id, String client_secret, String code, URI redirect_uri)	Returns a builder that can be used to build requests for authorization code grants.
AuthorizationCodePKCERequest.Builder	authorizationCodePKCE(String code, String code_verifier)	Returns a builder that can be used to build requests for authorization code grants using the Proof Key for Code Exchange (PKCE) flow.
AuthorizationCodePKCERequest.Builder	authorizationCodePKCE(String client_id, String code, String code_verifier, URI redirect_uri)	Returns a builder that can be used to build requests for authorization code grants using the Proof Key for Code Exchange (PKCE) flow.
AuthorizationCodePKCERefreshRequest.Builder	authorizationCodePKCERefresh()	Refresh the access token by using the authorization code flow with Proof Key for Code Exchange (PKCE).
AuthorizationCodePKCERefreshRequest.Builder	authorizationCodePKCERefresh(String client_id, String refresh_token)	Refresh the access token by using the authorization code flow with Proof Key for Code Exchange (PKCE).
AuthorizationCodeUriRequest.Builder	authorizationCodePKCEUri(String code_challenge)	Retrieve an URL where the user can give the application permissions using the Proof Key for Code Exchange (PKCE) flow.
AuthorizationCodeUriRequest.Builder	authorizationCodePKCEUri(String client_id, String code_challenge, URI redirect_uri)	Retrieve an URL where the user can give the application permissions using the Proof Key for Code Exchange (PKCE) flow.
AuthorizationCodeRefreshRequest.Builder	authorizationCodeRefresh()	Refresh the access token by using authorization code grant.
AuthorizationCodeRefreshRequest.Builder	authorizationCodeRefresh(String client_id, String client_secret, String refresh_token)	Refresh the access token by using authorization code grant.
AuthorizationCodeUriRequest.Builder	authorizationCodeUri()	Retrieve an URL where the user can give the application permissions.
AuthorizationCodeUriRequest.Builder	authorizationCodeUri(String client_id, URI redirect_uri)	Retrieve an URL where the user can give the application permissions.
static SpotifyApi.Builder	builder()	Create a builder for building a new Spotify API instance.
ChangePlaylistsDetailsRequest.Builder	changePlaylistsDetails(String playlist_id)	Update a playlists properties.
CheckCurrentUserFollowsArtistsOrUsersRequest.Builder	checkCurrentUserFollowsArtistsOrUsers(ModelObjectType type, String[] ids)	Check to see if the current user is following one or more artists or other Spotify users.
CheckUsersFollowPlaylistRequest.Builder	checkUsersFollowPlaylist(String playlist_id, String[] ids)	Check to see if one or more Spotify users are following a specified playlist.
CheckUsersFollowPlaylistRequest.Builder	checkUsersFollowPlaylist(String owner_id, String playlist_id, String[] ids)	Deprecated. since the endpoint no longer needs the owner_id param.
CheckUsersSavedAlbumsRequest.Builder	checkUsersSavedAlbums(String... ids)	Check if an album is saved in the user's "Your Music" library.
CheckUsersSavedEpisodesRequest.Builder	checkUsersSavedEpisodes(String... ids)	Check if one or more episodes is already saved in the current Spotify user's 'Your Episodes' library.
CheckUsersSavedShowsRequest.Builder	checkUsersSavedShows(String... ids)	Check if a show is saved in the users "Your Music" library.
CheckUsersSavedTracksRequest.Builder	checkUsersSavedTracks(String... ids)	Check if a track is saved in the user's "Your Music" library.
ClientCredentialsRequest.Builder	clientCredentials()	Returns a builder that can be used to build requests for client credential grants.
static String	concat(String[] parts, char character)	String concatenation helper method.
CreatePlaylistRequest.Builder	createPlaylist(String user_id, String name)	Create a playlist.
FollowArtistsOrUsersRequest.Builder	followArtistsOrUsers(ModelObjectType type, com.google.gson.JsonArray ids)	Add the current user as a follower of one or more artists or other Spotify users.
FollowArtistsOrUsersRequest.Builder	followArtistsOrUsers(ModelObjectType type, String[] ids)	Add the current user as a follower of one or more artists or other Spotify users.
FollowPlaylistRequest.Builder	followPlaylist(String playlist_id, boolean public_)	Add the current user as a follower of a playlist.
FollowPlaylistRequest.Builder	followPlaylist(String owner_id, String playlist_id, boolean public_)	Add the current user as a follower of a playlist.
static String	formatDefaultDate(Date date)	Formats a date, using the default spotify format.
String	getAccessToken()	Get the access token specified in the API object, which is used for API calls.
GetAlbumRequest.Builder	getAlbum(String id)	Returns an album with the ID given below.
GetAlbumsTracksRequest.Builder	getAlbumsTracks(String id)	Returns the tracks of the album with the ID given below.
GetArtistRequest.Builder	getArtist(String id)	Get an artist.
GetArtistsAlbumsRequest.Builder	getArtistsAlbums(String id)	Get the albums of a specific artist.
GetArtistsRelatedArtistsRequest.Builder	getArtistsRelatedArtists(String id)	Get artists related/similar to an artist.
GetArtistsTopTracksRequest.Builder	getArtistsTopTracks(String id, com.neovisionaries.i18n.CountryCode country)	Get the top tracks of an artist in a specific country.
GetAudioAnalysisForTrackRequest.Builder	getAudioAnalysisForTrack(String id)	Get a detailed audio analysis for a single track identified by its unique Spotify ID.
GetAudioFeaturesForSeveralTracksRequest.Builder	getAudioFeaturesForSeveralTracks(String... ids)	Get audio features for multiple tracks based on their Spotify IDs.
GetAudioFeaturesForTrackRequest.Builder	getAudioFeaturesForTrack(String id)	Get audio features for a track based on its Spotify ID.
GetAvailableGenreSeedsRequest.Builder	getAvailableGenreSeeds()	Retrieve a list of available genres seed parameter values for recommendations.
GetCategoryRequest.Builder	getCategory(String category_id)	Get a category.
GetCategorysPlaylistsRequest.Builder	getCategorysPlaylists(String category_id)	Get the playlists from a specific category.
String	getClientId()	Get the application client ID specified in this API object.
String	getClientSecret()	Get the application client secret specified in this API object.
GetCurrentUsersProfileRequest.Builder	getCurrentUsersProfile()	Get detailed profile information about the current user (including the current user’s username).
GetCurrentUsersRecentlyPlayedTracksRequest.Builder	getCurrentUsersRecentlyPlayedTracks()	Get tracks from the current user's recently played tracks.
GetCurrentUsersSavedAlbumsRequest.Builder	getCurrentUsersSavedAlbums()	Get a list of the albums saved in the current Spotify user’s "Your Music" library.
GetEpisodeRequest.Builder	getEpisode(String id)	Get an episode.
String	getHost()	Get the API host used for API calls.
IHttpManager	getHttpManager()	Get the IHttpManager used for API calls.
GetInformationAboutUsersCurrentPlaybackRequest.Builder	getInformationAboutUsersCurrentPlayback()	Get information about the user's current playback state, including context, track progress, and active device.
GetListOfCategoriesRequest.Builder	getListOfCategories()	Get a list of categories.
GetListOfCurrentUsersPlaylistsRequest.Builder	getListOfCurrentUsersPlaylists()	Get a list of the playlists owned or followed by the current Spotify user.
GetListOfFeaturedPlaylistsRequest.Builder	getListOfFeaturedPlaylists()	Get "Featured Playlists" of different countries which may match a specific language.
GetListOfNewReleasesRequest.Builder	getListOfNewReleases()	Get the newest releases from a specific country.
GetListOfUsersPlaylistsRequest.Builder	getListOfUsersPlaylists(String user_id)	Get an user's playlists.
GetPlaylistRequest.Builder	getPlaylist(String playlist_id)	Get a playlist.
GetPlaylistCoverImageRequest.Builder	getPlaylistCoverImage(String playlist_id)	Get the image used to represent a specific playlist.
GetPlaylistsItemsRequest.Builder	getPlaylistsItems(String playlist_id)	Get a playlist's items.
Integer	getPort()	Get the port used for API calls.
Integer	getProxyPassword()	Get the proxy password used for API calls.
Integer	getProxyPort()	Get the proxy port used for API calls.
String	getProxyUrl()	Get the proxy URL used for API calls.
Integer	getProxyUsername()	Get the proxy username used for API calls.
GetRecommendationsRequest.Builder	getRecommendations()	Create a playlist-style listening experience based on seed artists, tracks and genres.
URI	getRedirectURI()	Get the redirect URI of the application specified in this API object.
String	getRefreshToken()	Get the refresh token specified in the API object.
String	getScheme()	Get the scheme used for API calls.
GetSeveralAlbumsRequest.Builder	getSeveralAlbums(String... ids)	Get multiple albums.
GetSeveralArtistsRequest.Builder	getSeveralArtists(String... ids)	Get multiple artists.
GetSeveralEpisodesRequest.Builder	getSeveralEpisodes(String... ids)	Get multiple episodes.
GetSeveralShowsRequest.Builder	getSeveralShows(String... ids)	Get multiple shows.
GetSeveralTracksRequest.Builder	getSeveralTracks(String... ids)	Get multiple tracks.
GetShowRequest.Builder	getShow(String id)	Get a show.
GetShowsEpisodesRequest.Builder	getShowEpisodes(String id)	Get Spotify catalog information about an show’s episodes.
GetTheUsersQueueRequest.Builder	getTheUsersQueue()	Receive all items from the user's current playback queue.
GetTrackRequest.Builder	getTrack(String id)	Get a track.
GetUsersAvailableDevicesRequest.Builder	getUsersAvailableDevices()	Get information about an user's available devices.
GetUsersCurrentlyPlayingTrackRequest.Builder	getUsersCurrentlyPlayingTrack()	Get the object currently being played on the user's Spotify account.
GetUsersFollowedArtistsRequest.Builder	getUsersFollowedArtists(ModelObjectType type)	Get the current user’s followed artists.
GetUsersProfileRequest.Builder	getUsersProfile(String user_id)	Get public profile information about a Spotify user.
GetUsersSavedEpisodesRequest.Builder	getUsersSavedEpisodes()	Get a list of the episodes saved in the current Spotify user's library.
GetUsersSavedShowsRequest.Builder	getUsersSavedShows()	Get a list of shows saved in the current Spotify user’s library.
GetUsersSavedTracksRequest.Builder	getUsersSavedTracks()	Get an user's "Your Music" tracks.
GetUsersTopArtistsRequest.Builder	getUsersTopArtists()	Get the current user's top artists based on calculated affinity.
<T extends IArtistTrackModelObject> GetUsersTopArtistsAndTracksRequest.Builder<T>	getUsersTopArtistsAndTracks(ModelObjectType type)	Get the current user's top artists or tracks based on calculated affinity.
GetUsersTopTracksRequest.Builder	getUsersTopTracks()	Get the current user's top tracks based on calculated affinity.
static SimpleDateFormat	makeSimpleDateFormat(String pattern, String id)
static Date	parseDefaultDate(String date)	Parses a date in the default spotify format.
PauseUsersPlaybackRequest.Builder	pauseUsersPlayback()	Pause playback on the user's account.
RemoveAlbumsForCurrentUserRequest.Builder	removeAlbumsForCurrentUser(com.google.gson.JsonArray ids)	Remove one or more albums from the current user's "Your Music" library.
RemoveAlbumsForCurrentUserRequest.Builder	removeAlbumsForCurrentUser(String... ids)	Remove one or more albums from the current user's "Your Music" library.
RemoveItemsFromPlaylistRequest.Builder	removeItemsFromPlaylist(String playlist_id, com.google.gson.JsonArray tracks)	Delete items from a playlist
RemoveUsersSavedEpisodesRequest.Builder	removeUsersSavedEpisodes(com.google.gson.JsonArray ids)	Remove one or more episodes from the current user's library.
RemoveUsersSavedEpisodesRequest.Builder	removeUsersSavedEpisodes(String... ids)	Remove one or more episodes from the current user's library.
RemoveUsersSavedShowsRequest.Builder	removeUsersSavedShows(com.google.gson.JsonArray ids)	Remove one or more shows from the current users "Your Music" library.
RemoveUsersSavedShowsRequest.Builder	removeUsersSavedShows(String... ids)	Remove one or more shows from the current users "Your Music" library.
RemoveUsersSavedTracksRequest.Builder	removeUsersSavedTracks(com.google.gson.JsonArray ids)	Remove a track if saved to the user's "Your Music" library.
RemoveUsersSavedTracksRequest.Builder	removeUsersSavedTracks(String... ids)	Remove a track if saved to the user's "Your Music" library.
ReorderPlaylistsItemsRequest.Builder	reorderPlaylistsItems(String playlist_id, int range_start, int insert_before)	Reorder an item or a group of items in a playlist.
ReplacePlaylistsItemsRequest.Builder	replacePlaylistsItems(String playlist_id, com.google.gson.JsonArray uris)	Replace items in a playlist.
ReplacePlaylistsItemsRequest.Builder	replacePlaylistsItems(String playlist_id, String[] uris)	Replace items in a playlist.
SaveAlbumsForCurrentUserRequest.Builder	saveAlbumsForCurrentUser(com.google.gson.JsonArray ids)	Save albums in the user's "Your Music" library.
SaveAlbumsForCurrentUserRequest.Builder	saveAlbumsForCurrentUser(String... ids)	Save albums in the user's "Your Music" library.
SaveEpisodesForCurrentUserRequest.Builder	saveEpisodesForCurrentUser(com.google.gson.JsonArray ids)	Save one or more episodes to the current user's library.
SaveEpisodesForCurrentUserRequest.Builder	saveEpisodesForCurrentUser(String... ids)	Save one or more episodes to the current user's library.
SaveShowsForCurrentUserRequest.Builder	saveShowsForCurrentUser(com.google.gson.JsonArray ids)	Save one or more shows to current Spotify user’s library.
SaveShowsForCurrentUserRequest.Builder	saveShowsForCurrentUser(String... ids)	Save one or more shows to current Spotify user’s library.
SaveTracksForUserRequest.Builder	saveTracksForUser(com.google.gson.JsonArray ids)	Save tracks in the user's "Your Music" library.
SaveTracksForUserRequest.Builder	saveTracksForUser(String... ids)	Save tracks in the user's "Your Music" library.
SearchAlbumsRequest.Builder	searchAlbums(String q)	Get Spotify catalog information about albums that match a keyword string.
SearchAlbumsSpecialRequest.Builder	searchAlbumsSpecial(String q)	Get Spotify catalog information about albums that match a keyword string.
SearchArtistsRequest.Builder	searchArtists(String q)	Get Spotify catalog information about artists that match a keyword string.
SearchEpisodesRequest.Builder	searchEpisodes(String q)	Get Spotify catalog information about episodes that match a keyword string.
SearchItemRequest.Builder	searchItem(String q, String type)	Get Spotify catalog information about artists, albums, episodes, shows, tracks or playlists that match a keyword string.
SearchPlaylistsRequest.Builder	searchPlaylists(String q)	Get Spotify catalog information about playlists that match a keyword string.
SearchShowsRequest.Builder	searchShows(String q)	Get Spotify catalog information about shows that match a keyword string.
SearchTracksRequest.Builder	searchTracks(String q)	Get Spotify catalog information about tracks that match a keyword string.
SeekToPositionInCurrentlyPlayingTrackRequest.Builder	seekToPositionInCurrentlyPlayingTrack(int position_ms)	Seeks to the given position in the user's currently playing track.
void	setAccessToken(String accessToken)	Set the access token of the API object.
void	setRefreshToken(String refreshToken)	Set the refresh token of the API object.
SetRepeatModeOnUsersPlaybackRequest.Builder	setRepeatModeOnUsersPlayback(String state)	Set the repeat mode for the user's playback.
SetVolumeForUsersPlaybackRequest.Builder	setVolumeForUsersPlayback(int volume_percent)	Set the volume for the user's current playback device.
SkipUsersPlaybackToNextTrackRequest.Builder	skipUsersPlaybackToNextTrack()	Skips to next track in the user's queue.
SkipUsersPlaybackToPreviousTrackRequest.Builder	skipUsersPlaybackToPreviousTrack()	Skips to previous track in the user's queue.
StartResumeUsersPlaybackRequest.Builder	startResumeUsersPlayback()	Start a new context or resume current playback on the user's active device.
ToggleShuffleForUsersPlaybackRequest.Builder	toggleShuffleForUsersPlayback(boolean state)	Toggle shuffle on or off for user's playback.
TransferUsersPlaybackRequest.Builder	transferUsersPlayback(com.google.gson.JsonArray device_ids)	Transfer playback to a new device and determine if it should start playing.
UnfollowArtistsOrUsersRequest.Builder	unfollowArtistsOrUsers(ModelObjectType type, com.google.gson.JsonArray ids)	Remove the current user as a follower of one or more artists or other Spotify users.
UnfollowArtistsOrUsersRequest.Builder	unfollowArtistsOrUsers(ModelObjectType type, String[] ids)	Remove the current user as a follower of one or more artists or other Spotify users.
UnfollowPlaylistRequest.Builder	unfollowPlaylist(String playlist_id)	Remove the current user as a follower of a playlist.
UnfollowPlaylistRequest.Builder	unfollowPlaylist(String owner_id, String playlist_id)	Remove the specified user as a follower of a playlist.
UploadCustomPlaylistCoverImageRequest.Builder	uploadCustomPlaylistCoverImage(String playlist_id)	Replace the image used to represent a specific playlist.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

DEFAULT_AUTHENTICATION_HOST

public static final String DEFAULT_AUTHENTICATION_HOST

The default authentication host of Spotify API calls.

See Also:

• Constant Field Values

DEFAULT_AUTHENTICATION_PORT

public static final int DEFAULT_AUTHENTICATION_PORT

The default authentication port of Spotify API calls.

See Also:

• Constant Field Values

DEFAULT_AUTHENTICATION_SCHEME

public static final String DEFAULT_AUTHENTICATION_SCHEME

The default authentication http scheme of Spotify API calls.

See Also:

• Constant Field Values

DEFAULT_HOST

public static final String DEFAULT_HOST

The default host of Spotify API calls.

See Also:

• Constant Field Values

DEFAULT_HTTP_MANAGER

public static final IHttpManager DEFAULT_HTTP_MANAGER

A HttpManager configured with default settings.

DEFAULT_PORT

public static final int DEFAULT_PORT

The default port of Spotify API calls.

See Also:

• Constant Field Values

DEFAULT_SCHEME

public static final String DEFAULT_SCHEME

The default http scheme of Spotify API calls.

See Also:

• Constant Field Values

LOGGER

public static final Logger LOGGER

Method Details

builder

public static SpotifyApi.Builder builder()

Create a builder for building a new Spotify API instance.

Returns:

A SpotifyApi.Builder.

concat

public static String concat(String[] parts,
 char character)

String concatenation helper method.

Parameters:

parts - String parts.

character - Separation character.

Returns:

A string.

parseDefaultDate

public static Date parseDefaultDate(String date)
                             throws ParseException

Parses a date in the default spotify format.

Parameters:

date - the input date to parse

Returns:

the pared Date

Throws:

ParseException - if the date is not in a valid format

formatDefaultDate

public static String formatDefaultDate(Date date)

Formats a date, using the default spotify format.

Parameters:

date - the date to format

Returns:

the formatted date

makeSimpleDateFormat

public static SimpleDateFormat makeSimpleDateFormat(String pattern,
 String id)

getHttpManager

public IHttpManager getHttpManager()

Get the IHttpManager used for API calls.

Returns:

An IHttpManager.

getScheme

public String getScheme()

Get the scheme used for API calls. Default: https

Returns:

A scheme.

getHost

public String getHost()

Get the API host used for API calls. Default: "api.spotify.com"

Returns:

The host address.

getPort

public Integer getPort()

Get the port used for API calls. Default: 443

Returns:

A port.

getProxyUrl

public String getProxyUrl()

Get the proxy URL used for API calls.

Returns:

The proxy URL.

getProxyPort

public Integer getProxyPort()

Get the proxy port used for API calls.

Returns:

The proxy port.

getProxyUsername

public Integer getProxyUsername()

Get the proxy username used for API calls.

Returns:

The proxy username.

getProxyPassword

public Integer getProxyPassword()

Get the proxy password used for API calls.

Returns:

The proxy password.

getClientId

public String getClientId()

Get the application client ID specified in this API object.

Returns:

Application client ID.

getClientSecret

public String getClientSecret()

Get the application client secret specified in this API object.

Returns:

Application client secret.

getRedirectURI

public URI getRedirectURI()

Get the redirect URI of the application specified in this API object.

Returns:

Application redirect URI.

getAccessToken

public String getAccessToken()

Get the access token specified in the API object, which is used for API calls.

Returns:

A Spotify Web API access token.

setAccessToken

public void setAccessToken(String accessToken)

Set the access token of the API object.

Parameters:

accessToken - A Spotify Web API access token.

getRefreshToken

public String getRefreshToken()

Get the refresh token specified in the API object.

Returns:

A Spotify Web API refresh token.

setRefreshToken

public void setRefreshToken(String refreshToken)

Set the refresh token of the API object.

Parameters:

refreshToken - A Spotify Web API refresh token.

authorizationCodeRefresh

public AuthorizationCodeRefreshRequest.Builder authorizationCodeRefresh(String client_id,
 String client_secret,
 String refresh_token)

Refresh the access token by using authorization code grant.
Requires client ID, client secret, and refresh token to be set.

Parameters:

client_id - When you register your application, Spotify provides you a Client ID.

client_secret - When you register your application, Spotify provides you a Client Secret.

refresh_token - The refresh token returned from the authorization code exchange.

Returns:

An AuthorizationCodeRequest.Builder.

authorizationCodeRefresh

public AuthorizationCodeRefreshRequest.Builder authorizationCodeRefresh()

Refresh the access token by using authorization code grant.

Returns:

An AuthorizationCodeRequest.Builder.

authorizationCodePKCERefresh

public AuthorizationCodePKCERefreshRequest.Builder authorizationCodePKCERefresh(String client_id,
 String refresh_token)

Refresh the access token by using the authorization code flow with Proof Key for Code Exchange (PKCE).
Requires client ID and refresh token to be set.

Parameters:

client_id - When you register your application, Spotify provides you a Client ID.

refresh_token - The refresh token returned from the authorization code exchange or the last access token refresh.

Returns:

An AuthorizationCodePKCERefreshRequest.Builder.

authorizationCodePKCERefresh

public AuthorizationCodePKCERefreshRequest.Builder authorizationCodePKCERefresh()

Refresh the access token by using the authorization code flow with Proof Key for Code Exchange (PKCE).

Returns:

An AuthorizationCodePKCERefreshRequest.Builder.

authorizationCode

public AuthorizationCodeRequest.Builder authorizationCode(String client_id,
 String client_secret,
 String code,
 URI redirect_uri)

Returns a builder that can be used to build requests for authorization code grants.
Requires client ID, client secret, authorization code and redirect URI to be set.

Parameters:

client_id - When you register your application, Spotify provides you a Client ID.

client_secret - When you register your application, Spotify provides you a Client Secret.

code - The authorization code returned from the initial request to the Account /authorize endpoint.

redirect_uri - This parameter is used for validation only (there is no actual redirection). The value of this parameter must exactly match the value of redirect_uri supplied when requesting the authorization code.

Returns:

An AuthorizationCodeRequest.Builder.

authorizationCode

public AuthorizationCodeRequest.Builder authorizationCode(String code)

Returns a builder that can be used to build requests for authorization code grants.
Requires authorization code to be set.

Parameters:

code - The authorization code returned from the initial request to the Account /authorize endpoint.

Returns:

An AuthorizationCodeRequest.Builder.

authorizationCodePKCE

public AuthorizationCodePKCERequest.Builder authorizationCodePKCE(String client_id,
 String code,
 String code_verifier,
 URI redirect_uri)

Returns a builder that can be used to build requests for authorization code grants using the Proof Key for Code Exchange (PKCE) flow.
Requires client ID, authorization code, code verifier and redirect URI to be set.

Parameters:

client_id - When you register your application, Spotify provides you a Client ID.

code - The authorization code returned from the initial request to the Account /authorize endpoint.

code_verifier - The value of this parameter must match the value of the code_verifier that your app generated beforehand.

redirect_uri - This parameter is used for validation only (there is no actual redirection). The value of this parameter must exactly match the value of redirect_uri supplied when requesting the authorization code.

Returns:

An AuthorizationCodePKCERequest.Builder.

See Also:

• Authorization Code Flow with Proof Key for Code Exchange (PKCE)

authorizationCodePKCE

public AuthorizationCodePKCERequest.Builder authorizationCodePKCE(String code,
 String code_verifier)

Returns a builder that can be used to build requests for authorization code grants using the Proof Key for Code Exchange (PKCE) flow.
Requires authorization code and code verifier to be set.

Parameters:

code - The authorization code returned from the initial request to the Account /authorize endpoint.

code_verifier - The value of this parameter must match the value of the code_verifier that your app generated beforehand.

Returns:

An AuthorizationCodePKCERequest.Builder.

See Also:

• Authorization Code Flow with Proof Key for Code Exchange (PKCE)

authorizationCodeUri

public AuthorizationCodeUriRequest.Builder authorizationCodeUri(String client_id,
 URI redirect_uri)

Retrieve an URL where the user can give the application permissions.

Parameters:

client_id - When you register your application, Spotify provides you a Client ID.

redirect_uri - This parameter is used for validation only (there is no actual redirection). The value of this parameter must exactly match the value of redirect_uri supplied when requesting the authorization code.

Returns:

An AuthorizationCodeUriRequest.Builder.

authorizationCodeUri

public AuthorizationCodeUriRequest.Builder authorizationCodeUri()

Retrieve an URL where the user can give the application permissions.

Returns:

An AuthorizationCodeUriRequest.Builder.

authorizationCodePKCEUri

public AuthorizationCodeUriRequest.Builder authorizationCodePKCEUri(String client_id,
 String code_challenge,
 URI redirect_uri)

Retrieve an URL where the user can give the application permissions using the Proof Key for Code Exchange (PKCE) flow.

Parameters:

client_id - When you register your application, Spotify provides you a Client ID.

code_challenge - The code challenge that your app calculated beforehand. The code challenge is the base64url encoded sha256-hash of the code verifier, which is a cryptographically random string between 43 and 128 characters in length. It can contain letters, digits, underscores, periods, hyphens, or tildes and is generated by your app before each authentication request.

redirect_uri - This parameter is used for validation only (there is no actual redirection). The value of this parameter must exactly match the value of redirect_uri supplied when requesting the authorization code.

Returns:

An AuthorizationCodeUriRequest.Builder.

See Also:

• Authorization Code Flow with Proof Key for Code Exchange (PKCE)

authorizationCodePKCEUri

public AuthorizationCodeUriRequest.Builder authorizationCodePKCEUri(String code_challenge)

Retrieve an URL where the user can give the application permissions using the Proof Key for Code Exchange (PKCE) flow.

Parameters:

code_challenge - The code challenge that your app calculated beforehand. The code challenge is the base64url encoded sha256-hash of the code verifier, which is a cryptographically random string between 43 and 128 characters in length. It can contain letters, digits, underscores, periods, hyphens, or tildes and is generated

Returns:

An AuthorizationCodeUriRequest.Builder.

See Also:

• Authorization Code Flow with Proof Key for Code Exchange (PKCE)

clientCredentials

public ClientCredentialsRequest.Builder clientCredentials()

Returns a builder that can be used to build requests for client credential grants.
Requires client ID and client secret to be set.

Returns:

A ClientCredentialsRequest.Builder.

getAlbum

public GetAlbumRequest.Builder getAlbum(String id)

Returns an album with the ID given below.

Parameters:

id - The Spotify album ID of the album you're trying to retrieve.

Returns:

A GetAlbumRequest.Builder.

See Also:

• Spotify: URLs & IDs

getAlbumsTracks

public GetAlbumsTracksRequest.Builder getAlbumsTracks(String id)

Returns the tracks of the album with the ID given below.

Parameters:

id - The Spotify ID of the album you're trying to retrieve.

Returns:

A GetAlbumsTracksRequest.Builder.

See Also:

• Spotify: URLs & IDs

getSeveralAlbums

public GetSeveralAlbumsRequest.Builder getSeveralAlbums(String... ids)

Get multiple albums.

Parameters:

ids - The Spotify IDs of all albums you're trying to retrieve. Maximum: 20 IDs.

Returns:

A GetSeveralAlbumsRequest.Builder.

See Also:

• Spotify: URLs & IDs

getArtist

public GetArtistRequest.Builder getArtist(String id)

Get an artist.

Parameters:

id - The Spotify ID of the artist.

Returns:

A GetArtistRequest.Builder.

See Also:

• Spotify: URLs & IDs

getArtistsAlbums

public GetArtistsAlbumsRequest.Builder getArtistsAlbums(String id)

Get the albums of a specific artist.

Parameters:

id - The Spotify ID of the artist.

Returns:

A GetArtistsAlbumsRequest.Builder.

See Also:

• Spotify: URLs & IDs

getArtistsTopTracks

public GetArtistsTopTracksRequest.Builder getArtistsTopTracks(String id,
 com.neovisionaries.i18n.CountryCode country)

Get the top tracks of an artist in a specific country.

Parameters:

id - The Spotify ID of the artist.

country - The ISO 3166-1 alpha-2 country code of the specific country.

Returns:

A GetArtistsTopTracksRequest.Builder.

See Also:

• Spotify: URLs & IDs
• Wikipedia: ISO 3166-1 alpha-2 country codes

getArtistsRelatedArtists

public GetArtistsRelatedArtistsRequest.Builder getArtistsRelatedArtists(String id)

Get artists related/similar to an artist.

Parameters:

id - The Spotify ID of the artist.

Returns:

A GetArtistsRelatedArtistsRequest.Builder.

See Also:

• Spotify: URLs & IDs

getSeveralArtists

public GetSeveralArtistsRequest.Builder getSeveralArtists(String... ids)

Get multiple artists.

Parameters:

ids - The Spotify IDs of all artists you're trying to retrieve. Maximum: 50 IDs.

Returns:

A GetSeveralArtistsRequest.Builder.

See Also:

• Spotify: URLs & IDs

getCategory

public GetCategoryRequest.Builder getCategory(String category_id)

Get a category.

Parameters:

category_id - The Spotify category ID for the category.

Returns:

A GetCategoryRequest.Builder.

See Also:

• Spotify: URLs & IDs

getCategorysPlaylists

public GetCategorysPlaylistsRequest.Builder getCategorysPlaylists(String category_id)

Get the playlists from a specific category.

Parameters:

category_id - The Spotify category ID for the category.

Returns:

A GetCategorysPlaylistsRequest.Builder.

See Also:

• Spotify: URLs & IDs

getListOfCategories

public GetListOfCategoriesRequest.Builder getListOfCategories()

Get a list of categories.

Returns:

A GetListOfCategoriesRequest.Builder.

getListOfFeaturedPlaylists

public GetListOfFeaturedPlaylistsRequest.Builder getListOfFeaturedPlaylists()

Get "Featured Playlists" of different countries which may match a specific language.

Returns:

A GetListOfFeaturedPlaylistsRequest.Builder.

getListOfNewReleases

public GetListOfNewReleasesRequest.Builder getListOfNewReleases()

Get the newest releases from a specific country.

Returns:

A GetListOfNewReleasesRequest.Builder.

getRecommendations

public GetRecommendationsRequest.Builder getRecommendations()

Create a playlist-style listening experience based on seed artists, tracks and genres.

Returns:

A GetRecommendationsRequest.Builder.

getAvailableGenreSeeds

public GetAvailableGenreSeedsRequest.Builder getAvailableGenreSeeds()

Retrieve a list of available genres seed parameter values for recommendations.

Returns:

A GetAvailableGenreSeedsRequest.Builder.

getEpisode

public GetEpisodeRequest.Builder getEpisode(String id)

Get an episode.

Parameters:

id - The Spotify ID of the episode.

Returns:

A GetEpisodeRequest.Builder.

See Also:

• Spotify: URLs & IDs

getSeveralEpisodes

public GetSeveralEpisodesRequest.Builder getSeveralEpisodes(String... ids)

Get multiple episodes.

Parameters:

ids - The Spotify IDs of all episodes you're trying to retrieve. Maximum: 50 IDs.

Returns:

A GetSeveralEpisodesRequest.Builder.

See Also:

• Spotify: URLs & IDs

checkCurrentUserFollowsArtistsOrUsers

public CheckCurrentUserFollowsArtistsOrUsersRequest.Builder checkCurrentUserFollowsArtistsOrUsers(ModelObjectType type,
 String[] ids)

Check to see if the current user is following one or more artists or other Spotify users.

Parameters:

type - The ID type: either artist or user.

ids - A list of the artist or the user Spotify IDs to check. Maximum: 50 IDs.

Returns:

A CheckCurrentUserFollowsArtistsOrUsersRequest.Builder.

See Also:

• Spotify: URLs & IDs

checkUsersFollowPlaylist

@Deprecated(since="8.3.7")
public CheckUsersFollowPlaylistRequest.Builder checkUsersFollowPlaylist(String owner_id,
 String playlist_id,
 String[] ids)

Deprecated.

since the endpoint no longer needs the owner_id param. Use checkUsersFollowPlaylist(String, String[]) instead.

Check to see if one or more Spotify users are following a specified playlist.

Parameters:

owner_id - The Spotify User ID of the person who owns the playlist.

playlist_id - The Spotify ID of the playlist.

ids - A list of Spotify User IDs; the IDs of the users that you want to check to see if they follow the playlist. Maximum: 5 IDs.

Returns:

A CheckUsersFollowPlaylistRequest.Builder.

See Also:

• Spotify: URLs & IDs

checkUsersFollowPlaylist

public CheckUsersFollowPlaylistRequest.Builder checkUsersFollowPlaylist(String playlist_id,
 String[] ids)

Check to see if one or more Spotify users are following a specified playlist.

Parameters:

playlist_id - The Spotify ID of the playlist.

ids - A list of Spotify User IDs; the IDs of the users that you want to check to see if they follow the playlist. Maximum: 5 IDs.

Returns:

A CheckUsersFollowPlaylistRequest.Builder.

See Also:

• Spotify: URLs & IDs

followArtistsOrUsers

public FollowArtistsOrUsersRequest.Builder followArtistsOrUsers(ModelObjectType type,
 String[] ids)

Add the current user as a follower of one or more artists or other Spotify users.

Parameters:

type - The ID type: either artist or user.

ids - A list of the artist or the user Spotify IDs. Maximum: 50 IDs.

Returns:

A FollowArtistsOrUsersRequest.Builder.

See Also:

• Spotify: URLs & IDs

followArtistsOrUsers

public FollowArtistsOrUsersRequest.Builder followArtistsOrUsers(ModelObjectType type,
 com.google.gson.JsonArray ids)

Add the current user as a follower of one or more artists or other Spotify users.

Parameters:

type - The ID type: either artist or user.

ids - A list of the artist or the user Spotify IDs. Maximum: 50 IDs.

Returns:

A FollowArtistsOrUsersRequest.Builder.

See Also:

• Spotify: URLs & IDs

followPlaylist

public FollowPlaylistRequest.Builder followPlaylist(String owner_id,
 String playlist_id,
 boolean public_)

Add the current user as a follower of a playlist.

Parameters:

owner_id - The Spotify user ID of the person who owns the playlist.

playlist_id - The Spotify ID of the playlist. Any playlist can be followed, regardless of its public/private status, as long as you know its playlist ID.

public_ - Default: true. If true the playlist will be included in user's public playlists, if false it will remain private. To be able to follow playlists privately, the user must have granted the playlist-modify-private scope.

Returns:

A FollowPlaylistRequest.Builder.

See Also:

• Spotify: URLs & IDs

followPlaylist

public FollowPlaylistRequest.Builder followPlaylist(String playlist_id,
 boolean public_)

Add the current user as a follower of a playlist.

Parameters:

playlist_id - The Spotify ID of the playlist. Any playlist can be followed, regardless of its public/private status, as long as you know its playlist ID.

public_ - Default: true. If true the playlist will be included in user's public playlists, if false it will remain private. To be able to follow playlists privately, the user must have granted the playlist-modify-private scope.

Returns:

A FollowPlaylistRequest.Builder.

See Also:

• Spotify: URLs & IDs

getUsersFollowedArtists

public GetUsersFollowedArtistsRequest.Builder getUsersFollowedArtists(ModelObjectType type)

Get the current user’s followed artists.

Parameters:

type - The ID type: currently only artist is supported.

Returns:

A GetUsersFollowedArtistsRequest.Builder.

See Also:

• Spotify: URLs & IDs

unfollowArtistsOrUsers

public UnfollowArtistsOrUsersRequest.Builder unfollowArtistsOrUsers(ModelObjectType type,
 String[] ids)

Remove the current user as a follower of one or more artists or other Spotify users.

Parameters:

type - The ID type: either artist or user.

ids - A list of the artist or the user Spotify IDs. Maximum: 50 IDs.

Returns:

A UnfollowArtistsOrUsersRequest.Builder.

See Also:

• Spotify: URLs & IDs

unfollowArtistsOrUsers

public UnfollowArtistsOrUsersRequest.Builder unfollowArtistsOrUsers(ModelObjectType type,
 com.google.gson.JsonArray ids)

Remove the current user as a follower of one or more artists or other Spotify users.

Parameters:

type - The ID type: either artist or user.

ids - A JSON array of the artist or the user Spotify IDs. Maximum: 50 IDs.

Returns:

A UnfollowArtistsOrUsersRequest.Builder.

See Also:

• Spotify: URLs & IDs

unfollowPlaylist

public UnfollowPlaylistRequest.Builder unfollowPlaylist(String owner_id,
 String playlist_id)

Remove the specified user as a follower of a playlist.

Parameters:

owner_id - The owners username.

playlist_id - The playlist's ID.

Returns:

An UnfollowPlaylistRequest.Builder.

See Also:

• Spotify: URLs & IDs

unfollowPlaylist

public UnfollowPlaylistRequest.Builder unfollowPlaylist(String playlist_id)

Remove the current user as a follower of a playlist.

Parameters:

playlist_id - The playlist's ID.

Returns:

An UnfollowPlaylistRequest.Builder.

See Also:

• Spotify: URLs & IDs

checkUsersSavedAlbums

public CheckUsersSavedAlbumsRequest.Builder checkUsersSavedAlbums(String... ids)

Check if an album is saved in the user's "Your Music" library.

Parameters:

ids - The album IDs to check for in the user's Your Music library. Maximum: 50 IDs.

Returns:

A CheckUsersSavedAlbumsRequest.Builder.

See Also:

• Spotify: URLs & IDs

checkUsersSavedShows

public CheckUsersSavedShowsRequest.Builder checkUsersSavedShows(String... ids)

Check if a show is saved in the users "Your Music" library.

Parameters:

ids - The show IDs to check for in the user's Your Music library. Maximum: 50 IDs.

Returns:

A CheckUsersSavedShowsRequest.Builder.

See Also:

• Spotify: URLs & IDs

checkUsersSavedEpisodes

public CheckUsersSavedEpisodesRequest.Builder checkUsersSavedEpisodes(String... ids)

Check if one or more episodes is already saved in the current Spotify user's 'Your Episodes' library. This endpoint is in beta and could change without warning.

Parameters:

ids - The episode IDs to check for in the user's 'Your Episodes' library. Maximum: 50 IDs.

Returns:

A CheckUsersSavedEpisodesRequest.Builder.

See Also:

• Spotify: URLs & IDs

checkUsersSavedTracks

public CheckUsersSavedTracksRequest.Builder checkUsersSavedTracks(String... ids)

Check if a track is saved in the user's "Your Music" library.

Parameters:

ids - The track IDs to check for in the user's Your Music library. Maximum: 50 IDs.

Returns:

A CheckUsersSavedTracksRequest.Builder.

See Also:

• Spotify: URLs & IDs

getCurrentUsersSavedAlbums

public GetCurrentUsersSavedAlbumsRequest.Builder getCurrentUsersSavedAlbums()

Get a list of the albums saved in the current Spotify user’s "Your Music" library.

Returns:

A GetCurrentUsersSavedAlbumsRequest.Builder.

getUsersSavedShows

public GetUsersSavedShowsRequest.Builder getUsersSavedShows()

Get a list of shows saved in the current Spotify user’s library.

Returns:

A GetUsersSavedShowsRequest.Builder.

getUsersSavedEpisodes

public GetUsersSavedEpisodesRequest.Builder getUsersSavedEpisodes()

Get a list of the episodes saved in the current Spotify user's library. This endpoint is in beta and could change without warning.

Returns:

A GetUsersSavedEpisodesRequest.Builder.

getUsersSavedTracks

public GetUsersSavedTracksRequest.Builder getUsersSavedTracks()

Get an user's "Your Music" tracks.

Returns:

A GetUsersSavedTracksRequest.Builder.

removeAlbumsForCurrentUser

public RemoveAlbumsForCurrentUserRequest.Builder removeAlbumsForCurrentUser(String... ids)

Remove one or more albums from the current user's "Your Music" library.

Parameters:

ids - A list of the Spotify IDs. Maximum: 50 IDs.

Returns:

A RemoveAlbumsForCurrentUserRequest.Builder.

See Also:

• Spotify: URLs & IDs

removeAlbumsForCurrentUser

public RemoveAlbumsForCurrentUserRequest.Builder removeAlbumsForCurrentUser(com.google.gson.JsonArray ids)

Remove one or more albums from the current user's "Your Music" library.

Parameters:

ids - The Spotify IDs for the albums to be deleted. Maximum: 50 IDs.

Returns:

A RemoveAlbumsForCurrentUserRequest.Builder.

See Also:

• Spotify: URLs & IDs

removeUsersSavedShows

public RemoveUsersSavedShowsRequest.Builder removeUsersSavedShows(String... ids)

Remove one or more shows from the current users "Your Music" library.

Parameters:

ids - The Spotify IDs for the shows to be deleted. Maximum: 50 IDs.

Returns:

A RemoveAlbumsForCurrentUserRequest.Builder.

See Also:

• Spotify: URLs & IDs

removeUsersSavedShows

public RemoveUsersSavedShowsRequest.Builder removeUsersSavedShows(com.google.gson.JsonArray ids)

Remove one or more shows from the current users "Your Music" library.

Parameters:

ids - The Spotify IDs for the shows to be deleted. Maximum: 50 IDs.

Returns:

A RemoveAlbumsForCurrentUserRequest.Builder.

See Also:

• Spotify: URLs & IDs

removeUsersSavedEpisodes

public RemoveUsersSavedEpisodesRequest.Builder removeUsersSavedEpisodes(String... ids)

Remove one or more episodes from the current user's library. This endpoint is in beta and could change without warning.

Parameters:

ids - The Spotify IDs for the episodes to be removed. Maximum: 50 IDs.

Returns:

A RemoveUsersSavedEpisodesRequest.Builder.

See Also:

• Spotify: URLs & IDs

removeUsersSavedEpisodes

public RemoveUsersSavedEpisodesRequest.Builder removeUsersSavedEpisodes(com.google.gson.JsonArray ids)

Remove one or more episodes from the current user's library. This endpoint is in beta and could change without warning.

Parameters:

ids - The Spotify IDs for the episodes to be removed. Maximum: 50 IDs.

Returns:

A RemoveUsersSavedEpisodesRequest.Builder.

See Also:

• Spotify: URLs & IDs

removeUsersSavedTracks

public RemoveUsersSavedTracksRequest.Builder removeUsersSavedTracks(String... ids)

Remove a track if saved to the user's "Your Music" library.

Parameters:

ids - The track IDs to remove from the user's Your Music library. Maximum: 50 IDs.

Returns:

A RemoveUsersSavedTracksRequest.Builder.

See Also:

• Spotify: URLs & IDs

removeUsersSavedTracks

public RemoveUsersSavedTracksRequest.Builder removeUsersSavedTracks(com.google.gson.JsonArray ids)

Remove a track if saved to the user's "Your Music" library.

Parameters:

ids - The track IDs to remove from the user's Your Music library. Maximum: 50 IDs.

Returns:

A RemoveUsersSavedTracksRequest.Builder.

See Also:

• Spotify: URLs & IDs

saveAlbumsForCurrentUser

public SaveAlbumsForCurrentUserRequest.Builder saveAlbumsForCurrentUser(String... ids)

Save albums in the user's "Your Music" library.

Parameters:

ids - The album IDs to add to the user's library. Maximum: 50 IDs.

Returns:

A SaveAlbumsForCurrentUserRequest.Builder.

See Also:

• Spotify: URLs & IDs

saveAlbumsForCurrentUser

public SaveAlbumsForCurrentUserRequest.Builder saveAlbumsForCurrentUser(com.google.gson.JsonArray ids)

Save albums in the user's "Your Music" library.

Parameters:

ids - The album IDs to add to the user's library. Maximum: 50 IDs.

Returns:

A SaveAlbumsForCurrentUserRequest.Builder.

See Also:

• Spotify: URLs & IDs

saveShowsForCurrentUser

public SaveShowsForCurrentUserRequest.Builder saveShowsForCurrentUser(String... ids)

Save one or more shows to current Spotify user’s library.

Parameters:

ids - The show IDs to add to the user's library. Maximum: 50 IDs.

Returns:

A SaveShowsForCurrentUserRequest.Builder.

See Also:

• Spotify: URLs & IDs

saveShowsForCurrentUser

public SaveShowsForCurrentUserRequest.Builder saveShowsForCurrentUser(com.google.gson.JsonArray ids)

Save one or more shows to current Spotify user’s library.

Parameters:

ids - The show IDs to add to the user's library. Maximum: 50 IDs.

Returns:

A SaveShowsForCurrentUserRequest.Builder.

See Also:

• Spotify: URLs & IDs

saveEpisodesForCurrentUser

public SaveEpisodesForCurrentUserRequest.Builder saveEpisodesForCurrentUser(String... ids)

Save one or more episodes to the current user's library. This endpoint is in beta and could change without warning.

Parameters:

ids - The episode IDs to add to the user's library. Maximum: 50 IDs.

Returns:

A SaveEpisodesForCurrentUserRequest.Builder.

See Also:

• Spotify: URLs & IDs

saveEpisodesForCurrentUser

public SaveEpisodesForCurrentUserRequest.Builder saveEpisodesForCurrentUser(com.google.gson.JsonArray ids)

Save one or more episodes to the current user's library. This endpoint is in beta and could change without warning.

Parameters:

ids - The episode IDs to add to the user's library. Maximum: 50 IDs.

Returns:

A SaveEpisodesForCurrentUserRequest.Builder.

See Also:

• Spotify: URLs & IDs

saveTracksForUser

public SaveTracksForUserRequest.Builder saveTracksForUser(String... ids)

Save tracks in the user's "Your Music" library.

Parameters:

ids - The track IDs to add to the user's library. Maximum: 50 IDs.

Returns:

A SaveTracksForUserRequest.Builder.

See Also:

• Spotify: URLs & IDs

saveTracksForUser

public SaveTracksForUserRequest.Builder saveTracksForUser(com.google.gson.JsonArray ids)

Save tracks in the user's "Your Music" library.

Parameters:

ids - The track IDs to add to the user's library. Maximum: 50 IDs.

Returns:

A SaveTracksForUserRequest.Builder.

See Also:

• Spotify: URLs & IDs

getUsersTopArtistsAndTracks

public <T extends IArtistTrackModelObject>
GetUsersTopArtistsAndTracksRequest.Builder<T> getUsersTopArtistsAndTracks(ModelObjectType type)

Get the current user's top artists or tracks based on calculated affinity.

Affinity is a measure of the expected preference an user has for a particular track or artist. It is based on user behavior, including play history, but does not include actions made while in incognito mode. Light or infrequent users of Spotify may not have sufficient play history to generate a full affinity data set.

Type Parameters:

T - Either Artist or Track

Parameters:

type - The type of entity to return. Valid values: artists or tracks.

Returns:

A GetUsersTopArtistsAndTracksRequest.Builder.

getUsersTopArtists

public GetUsersTopArtistsRequest.Builder getUsersTopArtists()

Get the current user's top artists based on calculated affinity.

Returns:

A GetUsersTopArtistsRequest.Builder.

See Also:

• getUsersTopArtistsAndTracks(ModelObjectType)

getUsersTopTracks

public GetUsersTopTracksRequest.Builder getUsersTopTracks()

Get the current user's top tracks based on calculated affinity.

Returns:

A GetUsersTopTracksRequest.Builder.

See Also:

• getUsersTopArtistsAndTracks(ModelObjectType)

getInformationAboutUsersCurrentPlayback

public GetInformationAboutUsersCurrentPlaybackRequest.Builder getInformationAboutUsersCurrentPlayback()

Get information about the user's current playback state, including context, track progress, and active device.

Returns:

A GetInformationAboutUsersCurrentPlaybackRequest.Builder.

getCurrentUsersRecentlyPlayedTracks

public GetCurrentUsersRecentlyPlayedTracksRequest.Builder getCurrentUsersRecentlyPlayedTracks()

Get tracks from the current user's recently played tracks.

Returns the most recent 50 tracks played by an user. Note that a track currently playing will not be visible in play history until it has completed. A track must be played for more than 30 seconds to be included in play history.

Any tracks listened to while the user had "Private Session" enabled in their client will not be returned in the list of recently played tracks.

Returns:

A GetCurrentUsersRecentlyPlayedTracksRequest.Builder.

getUsersAvailableDevices

public GetUsersAvailableDevicesRequest.Builder getUsersAvailableDevices()

Get information about an user's available devices.

Returns:

A GetUsersAvailableDevicesRequest.Builder.

getUsersCurrentlyPlayingTrack

public GetUsersCurrentlyPlayingTrackRequest.Builder getUsersCurrentlyPlayingTrack()

Get the object currently being played on the user's Spotify account.

Returns:

A GetUsersCurrentlyPlayingTrackRequest.Builder.

pauseUsersPlayback

public PauseUsersPlaybackRequest.Builder pauseUsersPlayback()

Pause playback on the user's account.

Returns:

A PauseUsersPlaybackRequest.Builder.

seekToPositionInCurrentlyPlayingTrack

public SeekToPositionInCurrentlyPlayingTrackRequest.Builder seekToPositionInCurrentlyPlayingTrack(int position_ms)

Seeks to the given position in the user's currently playing track.

Parameters:

position_ms - The position in milliseconds to seek to. Must be a positive number. Passing in a position that is greater than the length of the track will cause the player to start playing the next song.

Returns:

A SeekToPositionInCurrentlyPlayingTrackRequest.Builder.

setRepeatModeOnUsersPlayback

public SetRepeatModeOnUsersPlaybackRequest.Builder setRepeatModeOnUsersPlayback(String state)

Set the repeat mode for the user's playback. Options are repeat-track, repeat-context, and off.

Parameters:

state - track, context or off. track will repeat the current track. context will repeat the current context. off will turn repeat off.

Returns:

A SetRepeatModeOnUsersPlaybackRequest.Builder.

setVolumeForUsersPlayback

public SetVolumeForUsersPlaybackRequest.Builder setVolumeForUsersPlayback(int volume_percent)

Set the volume for the user's current playback device.

Parameters:

volume_percent - Integer. The volume to set. Must be a value from 0 to 100 inclusive.

Returns:

A SetVolumeForUsersPlaybackRequest.Builder.

skipUsersPlaybackToNextTrack

public SkipUsersPlaybackToNextTrackRequest.Builder skipUsersPlaybackToNextTrack()

Skips to next track in the user's queue.

Returns:

A SkipUsersPlaybackToNextTrackRequest.Builder.

skipUsersPlaybackToPreviousTrack

public SkipUsersPlaybackToPreviousTrackRequest.Builder skipUsersPlaybackToPreviousTrack()

Skips to previous track in the user's queue.

Note: This will ALWAYS skip to the previous track, regardless of the current track’s progress. Returning to the start of the current track should be performed using the seekToPositionInCurrentlyPlayingTrack(int) method.

Returns:

A SkipUsersPlaybackToPreviousTrackRequest.Builder.

startResumeUsersPlayback

public StartResumeUsersPlaybackRequest.Builder startResumeUsersPlayback()

Start a new context or resume current playback on the user's active device.

Returns:

A StartResumeUsersPlaybackRequest.Builder.

toggleShuffleForUsersPlayback

public ToggleShuffleForUsersPlaybackRequest.Builder toggleShuffleForUsersPlayback(boolean state)

Toggle shuffle on or off for user's playback.

Parameters:

state - true: Shuffle user's playback. false: Do not shuffle user's playback.

Returns:

A ToggleShuffleForUsersPlaybackRequest.Builder.

transferUsersPlayback

public TransferUsersPlaybackRequest.Builder transferUsersPlayback(com.google.gson.JsonArray device_ids)

Transfer playback to a new device and determine if it should start playing.

Parameters:

device_ids - A JSON array containing the ID of the device on which playback should be started/transferred.
Note: Although an array is accepted, only a single device_id is currently supported.

Returns:

A TransferUsersPlaybackRequest.Builder.

addItemToUsersPlaybackQueue

public AddItemToUsersPlaybackQueueRequest.Builder addItemToUsersPlaybackQueue(String uri)

Add a track or an episode to the end of the user's current playback queue.

Parameters:

uri - The uri of the item to add to the queue. Must be a track or an episode uri.

Returns:

A AddItemToUsersPlaybackQueueRequest.Builder.

See Also:

• Spotify: URLs & IDs

getTheUsersQueue

public GetTheUsersQueueRequest.Builder getTheUsersQueue()

Receive all items from the user's current playback queue.

Returns:

An GetTheUsersQueueRequest.Builder.

addItemsToPlaylist

public AddItemsToPlaylistRequest.Builder addItemsToPlaylist(String playlist_id,
 String[] uris)

Add items to a playlist.

Note: If you want to add a large number of items (>50), use addItemsToPlaylist(String, JsonArray) to not exceed the maximum URI length.

Parameters:

playlist_id - The playlists ID.

uris - URIs of the tracks or episodes to add. Maximum: 100 item URIs.

Returns:

An AddItemsToPlaylistRequest.Builder.

See Also:

• Spotify: URLs & IDs

addItemsToPlaylist

public AddItemsToPlaylistRequest.Builder addItemsToPlaylist(String playlist_id,
 com.google.gson.JsonArray uris)

Add items to a playlist.

Parameters:

playlist_id - The playlists ID.

uris - URIs of the tracks or episodes to add. Maximum: 100 item URIs.

Returns:

An AddItemsToPlaylistRequest.Builder.

See Also:

• Spotify: URLs & IDs

changePlaylistsDetails

public ChangePlaylistsDetailsRequest.Builder changePlaylistsDetails(String playlist_id)

Update a playlists properties.

Parameters:

playlist_id - The playlists ID.

Returns:

A ChangePlaylistsDetailsRequest.Builder.

See Also:

• Spotify: URLs & IDs

createPlaylist

public CreatePlaylistRequest.Builder createPlaylist(String user_id,
 String name)

Create a playlist.

Parameters:

user_id - The playlists owner.

name - The name of the playlist.

Returns:

A CreatePlaylistRequest.Builder.

See Also:

• Spotify: URLs & IDs

getListOfCurrentUsersPlaylists

public GetListOfCurrentUsersPlaylistsRequest.Builder getListOfCurrentUsersPlaylists()

Get a list of the playlists owned or followed by the current Spotify user.

Returns:

A GetListOfCurrentUsersPlaylistsRequest.Builder.

getListOfUsersPlaylists

public GetListOfUsersPlaylistsRequest.Builder getListOfUsersPlaylists(String user_id)

Get an user's playlists.

Parameters:

user_id - A Spotify ID of the user.

Returns:

A GetListOfUsersPlaylistsRequest.Builder.

See Also:

• Spotify: URLs & IDs

getPlaylist

public GetPlaylistRequest.Builder getPlaylist(String playlist_id)

Get a playlist.

Parameters:

playlist_id - The playlists ID.

Returns:

A GetPlaylistRequest.Builder.

See Also:

• Spotify: URLs & IDs

getPlaylistCoverImage

public GetPlaylistCoverImageRequest.Builder getPlaylistCoverImage(String playlist_id)

Get the image used to represent a specific playlist.

Parameters:

playlist_id - The Spotify ID for the playlist.

Returns:

A GetPlaylistCoverImageRequest.Builder.

See Also:

• Spotify: URLs & IDs

getPlaylistsItems

public GetPlaylistsItemsRequest.Builder getPlaylistsItems(String playlist_id)

Get a playlist's items.

Parameters:

playlist_id - The playlists ID.

Returns:

A GetPlaylistsItemsRequest.Builder.

See Also:

• Spotify: URLs & IDs

removeItemsFromPlaylist

public RemoveItemsFromPlaylistRequest.Builder removeItemsFromPlaylist(String playlist_id,
 com.google.gson.JsonArray tracks)

Delete items from a playlist

Parameters:

playlist_id - The playlists ID.

tracks - URIs of the items to remove. Maximum: 100 track or episode URIs.

Returns:

A RemoveItemsFromPlaylistRequest.Builder.

See Also:

• Spotify: URLs & IDs

reorderPlaylistsItems

public ReorderPlaylistsItemsRequest.Builder reorderPlaylistsItems(String playlist_id,
 int range_start,
 int insert_before)

Reorder an item or a group of items in a playlist.

When reordering items, the timestamp indicating when they were added and the user who added them will be kept untouched. In addition, the users following the playlists won’t be notified about changes in the playlists when the items are reordered.

Parameters:

playlist_id - The Spotify ID for the playlist.

range_start - The position of the first item to be reordered.

insert_before - The position where the items should be inserted. To reorder the items to the end of the playlist, simply set insert_before to the position after the last item.

Returns:

A ReorderPlaylistsItemsRequest.Builder.

See Also:

• Spotify: URLs & IDs

replacePlaylistsItems

public ReplacePlaylistsItemsRequest.Builder replacePlaylistsItems(String playlist_id,
 String[] uris)

Replace items in a playlist.

Parameters:

playlist_id - The playlists ID.

uris - URIs of the items to set. Maximum: 100 track or episode URIs.

Returns:

A ReplacePlaylistsItemsRequest.Builder.

See Also:

• Spotify: URLs & IDs

replacePlaylistsItems

public ReplacePlaylistsItemsRequest.Builder replacePlaylistsItems(String playlist_id,
 com.google.gson.JsonArray uris)

Replace items in a playlist.

Parameters:

playlist_id - The playlists ID.

uris - URIs of the items to add. Maximum: 100 track or episode URIs.

Returns:

A ReplacePlaylistsItemsRequest.Builder.

See Also:

• Spotify: URLs & IDs

uploadCustomPlaylistCoverImage

public UploadCustomPlaylistCoverImageRequest.Builder uploadCustomPlaylistCoverImage(String playlist_id)

Replace the image used to represent a specific playlist.

Parameters:

playlist_id - The Spotify ID for the playlist.

Returns:

An UploadCustomPlaylistCoverImageRequest.Builder.

See Also:

• Spotify: URLs & IDs

searchItem

public SearchItemRequest.Builder searchItem(String q,
 String type)

Get Spotify catalog information about artists, albums, episodes, shows, tracks or playlists that match a keyword string.

Parameters:

q - The search query's keywords (and optional field filters and operators).

type - A comma-separated list of item types to search across. Valid types are: album, artist, episode, show, playlist and track.

Returns:

A SearchItemRequest.Builder.

searchAlbums

public SearchAlbumsRequest.Builder searchAlbums(String q)

Get Spotify catalog information about albums that match a keyword string.

Parameters:

q - The search query's keywords (and optional field filters and operators).

Returns:

A SearchAlbumsRequest.Builder.

searchAlbumsSpecial

public SearchAlbumsSpecialRequest.Builder searchAlbumsSpecial(String q)

Get Spotify catalog information about albums that match a keyword string.

This method exists because the searches API returns the undocumented property totalTracks, which is included by this method's return type.

Parameters:

q - The search query's keywords (and optional field filters and operators).

Returns:

A SearchAlbumsSpecialRequest.Builder.

searchArtists

public SearchArtistsRequest.Builder searchArtists(String q)

Get Spotify catalog information about artists that match a keyword string.

Parameters:

q - The search query's keywords (and optional field filters and operators).

Returns:

A SearchArtistsRequest.Builder.

searchEpisodes

public SearchEpisodesRequest.Builder searchEpisodes(String q)

Get Spotify catalog information about episodes that match a keyword string.

Parameters:

q - The search query's keywords (and optional field filters and operators).

Returns:

A SearchEpisodesRequest.Builder.

searchPlaylists

public SearchPlaylistsRequest.Builder searchPlaylists(String q)

Get Spotify catalog information about playlists that match a keyword string.

Parameters:

q - The search query's keywords (and optional field filters and operators).

Returns:

A SearchPlaylistsRequest.Builder.

searchShows

public SearchShowsRequest.Builder searchShows(String q)

Get Spotify catalog information about shows that match a keyword string.

Parameters:

q - The search query's keywords (and optional field filters and operators).

Returns:

A SearchShowsRequest.Builder.

searchTracks

public SearchTracksRequest.Builder searchTracks(String q)

Get Spotify catalog information about tracks that match a keyword string.

Parameters:

q - The search query's keywords (and optional field filters and operators).

Returns:

A SearchTracksRequest.Builder.

getShow

public GetShowRequest.Builder getShow(String id)

Get a show.

Parameters:

id - The Spotify ID of the show.

Returns:

A GetShowRequest.Builder.

See Also:

• Spotify: URLs & IDs

getSeveralShows

public GetSeveralShowsRequest.Builder getSeveralShows(String... ids)

Get multiple shows.

Parameters:

ids - The Spotify IDs of all shows you're trying to retrieve. Maximum: 50 IDs.

Returns:

A GetSeveralShowsRequest.Builder.

See Also:

• Spotify: URLs & IDs

getShowEpisodes

public GetShowsEpisodesRequest.Builder getShowEpisodes(String id)

Get Spotify catalog information about an show’s episodes.

Parameters:

id - The Spotify ID of the show.

Returns:

A GetShowsEpisodesRequest.Builder.

See Also:

• Spotify: URLs & IDs

getAudioAnalysisForTrack

public GetAudioAnalysisForTrackRequest.Builder getAudioAnalysisForTrack(String id)

Get a detailed audio analysis for a single track identified by its unique Spotify ID.

Parameters:

id - The Spotify ID for the track.

Returns:

A GetAudioAnalysisForTrackRequest.Builder.

See Also:

• Spotify: URLs & IDs

getAudioFeaturesForTrack

public GetAudioFeaturesForTrackRequest.Builder getAudioFeaturesForTrack(String id)

Get audio features for a track based on its Spotify ID.

Parameters:

id - The Spotify ID of the track.

Returns:

A GetAudioFeaturesForTrackRequest.Builder.

See Also:

• Spotify: URLs & IDs

getAudioFeaturesForSeveralTracks

public GetAudioFeaturesForSeveralTracksRequest.Builder getAudioFeaturesForSeveralTracks(String... ids)

Get audio features for multiple tracks based on their Spotify IDs.

Parameters:

ids - A comma-separated list of the Spotify IDs for the tracks. Maximum: 100 IDs.

Returns:

A GetAudioFeaturesForSeveralTracksRequest.Builder.

See Also:

• Spotify: URLs & IDs

getSeveralTracks

public GetSeveralTracksRequest.Builder getSeveralTracks(String... ids)

Get multiple tracks.

Parameters:

ids - The Spotify IDs of all tracks you're trying to retrieve. Maximum: 50 IDs.

Returns:

A GetSeveralTracksRequest.Builder.

See Also:

• Spotify: URLs & IDs

getTrack

public GetTrackRequest.Builder getTrack(String id)

Get a track.

Parameters:

id - The Spotify ID of the track.

Returns:

A GetTrackRequest.Builder.

See Also:

• Spotify: URLs & IDs

getCurrentUsersProfile

public GetCurrentUsersProfileRequest.Builder getCurrentUsersProfile()

Get detailed profile information about the current user (including the current user’s username).

Returns:

A GetCurrentUsersProfileRequest.Builder.

getUsersProfile

public GetUsersProfileRequest.Builder getUsersProfile(String user_id)

Get public profile information about a Spotify user.

Parameters:

user_id - The Spotify ID of the user.

Returns:

A GetUsersProfileRequest.Builder.

See Also:

• Spotify: URLs & IDs