SKCatalog Structure Reference

local
The local catalog instance, which represents the user’s region settings at the time the property is read.
Declaration
Swift

public static var local: SKCatalog { get }
locale
The locale representing the specific storefront/market from which to request catalog content.

All requests that include a market, country, or locale parameter will refer to the region and language codes provided by this property. If set to nil, many requests will return results for all available markets.

Important
Some requests are required to specify a locale or country code, and will result in an error if no locale is set before performing the request. This requirement will be annotated by all applicable requests.
Declaration
Swift

public var locale: Locale?


                    
                    
                    init(locale:)

Creates a new, reusable catalog instance with the specified storefront.

Declaration

Swift

public init(locale: Locale?)

Parameters


                                locale

The storefront/market from which to request catalog content.

Get an Album


                    
                    
                    makeAlbumRequest(id:)

Creates and returns the request used to get an album.

Declaration

Swift

public func makeAlbumRequest(id: String) -> SKRequest

Parameters

`id`	The Spotify ID for the album.

Return Value

An SKRequest instance with which to perform the API request.


                    
                    
                    getAlbum(withID:completion:)

Gets Spotify catalog information for a single album.

Declaration

Swift

public func getAlbum(withID id: String, completion handler: @escaping (SKAlbum?, Error?) -> Void)

Parameters

`id`	The Spotify ID for the album.
`handler`	The callback handler for the request. The parameters for this handler are: `album`: The requested full album, if available. `error`: An error identifying if and why the request failed, or `nil` if the request was successful.

Get Several Albums


                    
                    
                    makeAlbumsRequest(ids:)

Creates and returns the request used to get several albums.

Declaration

Swift

public func makeAlbumsRequest(ids: [String]) -> SKRequest

Parameters

ids

A list of the Spotify IDs for the albums. Maximum: 20 IDs.

Return Value

An SKRequest instance with which to perform the API request.


                    
                    
                    getAlbums(withIDs:completion:)

Gets Spotify catalog information for multiple albums identified by their Spotify IDs.

Declaration

Swift

public func getAlbums(withIDs ids: [String], completion handler: @escaping ([SKAlbum?]?, Error?) -> Void)

Parameters

`ids`	A list of the Spotify IDs for the albums. Maximum: 20 IDs.
`handler`	The callback handler for the request. The parameters for this handler are: `albums`: The requested list of full albums. If a particular album cannot be found for a given ID, the resulting array will contain `nil` at the corresponding index. `error`: An error identifying if and why the request failed, or `nil` if the request was successful.

Get an Artist


                    
                    
                    makeArtistRequest(id:)

Creates and returns the request used to get an artist.

Declaration

Swift

public func makeArtistRequest(id: String) -> SKRequest

Parameters

`id`	The Spotify ID for the artist.

Return Value

An SKRequest instance with which to perform the API request.


                    
                    
                    getArtist(withID:completion:)

Gets Spotify catalog information for a single artist identified by their unique Spotify ID.

Declaration

Swift

public func getArtist(withID id: String, completion handler: @escaping (SKArtist?, Error?) -> Void)

Parameters

`id`	The Spotify ID for the artist.
`handler`	The callback handler for the request. The parameters for this handler are: `artist`: The requested full artist, if available. `error`: An error identifying if and why the request failed, or `nil` if the request was successful.

Get Several Artists


                    
                    
                    makeArtistsRequest(ids:)

Creates and returns the request used to get several artists.

Declaration

Swift

public func makeArtistsRequest(ids: [String]) -> SKRequest

Parameters

ids

A list of the Spotify IDs for the artists. Maximum: 50 IDs.

Return Value

An SKRequest instance with which to perform the API request.


                    
                    
                    getArtists(withIDs:completion:)

Gets Spotify catalog information for several artists based on their Spotify IDs.

Declaration

Swift

public func getArtists(withIDs ids: [String], completion handler: @escaping ([SKArtist?]?, Error?) -> Void)

Parameters

`ids`	A list of the Spotify IDs for the artists. Maximum: 50 IDs.
`handler`	The callback handler for the request. The parameters for this handler are: `albums`: The requested list of full artists. If a particular artist cannot be found for a given ID, the resulting array will contain `nil` at the corresponding index. `error`: An error identifying if and why the request failed, or `nil` if the request was successful.

Get a Track


                    
                    
                    makeTrackRequest(id:)

Creates and returns the request used to get a track.

Declaration

Swift

public func makeTrackRequest(id: String) -> SKRequest

Parameters

`id`	The Spotify ID for the track.

Return Value

An SKRequest instance with which to perform the API request.


                    
                    
                    getTrack(withID:completion:)

Gets Spotify catalog information for a single track identified by its unique Spotify ID.

Declaration

Swift

public func getTrack(withID id: String, completion handler: @escaping (SKTrack?, Error?) -> Void)

Parameters

`id`	The Spotify ID for the track.
`handler`	The callback handler for the request. The parameters for this handler are: `track`: The requested full track, if available. `error`: An error identifying if and why the request failed, or `nil` if the request was successful.

Get Several Tracks


                    
                    
                    makeTracksRequest(ids:)

Creates and returns the request used to get several tracks.

Declaration

Swift

public func makeTracksRequest(ids: [String]) -> SKRequest

Parameters

ids

A list of the Spotify IDs for the tracks. Maximum: 50 IDs.

Return Value

An SKRequest instance with which to perform the API request.


                    
                    
                    getTracks(withIDs:completion:)

Gets Spotify catalog information for multiple tracks based on their Spotify IDs.

Declaration

Swift

public func getTracks(withIDs ids: [String], completion handler: @escaping ([SKTrack?]?, Error?) -> Void)

Parameters

`ids`	A list of the Spotify IDs for the tracks. Maximum: 50 IDs.
`handler`	The callback handler for the request. The parameters for this handler are: `tracks`: The requested list of full tracks. If a particular track cannot be found for a given ID, the resulting array will contain `nil` at the corresponding index. `error`: An error identifying if and why the request failed, or `nil` if the request was successful.

Get Featured Playlists


                    
                    
                    makeFeaturedPlaylistsRequest(date:page:)

Creates and returns the request used to get a list of Spotify featured playlists.

Note

If a catalog locale has not been specified (i.e., locale is set to nil), or if the specified language is not available, all strings will be returned in the Spotify default language (American English).

Declaration

Swift

public func makeFeaturedPlaylistsRequest(date: Date?, page: Pagination?) -> SKRequest

Parameters


                                date

A timestamp used to tailor results to a specific date and time of day. For example, if retrieving featured playlists for 3:00 PM, 23 October 2014, the catalog would return a list of playlists relevant to that time and day of the week, accompanied by a specific localized message (e.g., Get ready to rock your Thursday! #Rocktober). If nil is provided, the response defaults to the current UTC time.


                                page

The parameters for paginating the results, specifying the index and number of items to return. If no parameters are supplied, the request will return the default number of items beginning with first item.

Return Value

An SKRequest instance with which to perform the API request.


                    
                    
                    getFeaturedPlaylists(for:page:completion:)

Gets a list of Spotify featured playlists (for example, those shown on a Spotify player’s Browse tab).

Note

If a catalog locale has not been specified (i.e., locale is set to nil), or if the specified language is not available, all strings will be returned in the Spotify default language (American English).

Declaration

Swift

public func getFeaturedPlaylists(for date: Date? = Date(), page: Pagination? = nil, completion handler: @escaping (SKFeaturedPlaylists?, Error?) -> Void)

Parameters

`date`	A timestamp used to tailor results to a specific date and time of day. For example, if retrieving featured playlists for 3:00 PM, 23 October 2014, the catalog would return a list of playlists relevant to that time and day of the week, accompanied by a specific localized message (e.g., Get ready to rock your Thursday! #Rocktober). If `nil` is provided, the response defaults to the current UTC time. The default value is the current date and time, relative to the user’s current time zone.
`page`	The parameters for paginating the results, specifying the index and number of items to return. If no parameters are supplied, the request will return the default number of items beginning with first item. The default value is `nil`.
`handler`	The callback handler for the request. The parameters for this handler are: `featuredPlaylists`: An `SKFeaturedPlaylists` instance, which contains a paginated collection of playlists accompanied by a localized message string. `error`: An error identifying if and why the request failed, or `nil` if the request was successful.

Get New Releases


                    
                    
                    makeNewReleasesRequest(page:)

Creates and returns the request used to get a list of new album releases.

Declaration

Swift

public func makeNewReleasesRequest(page: Pagination?) -> SKRequest

Parameters


                                page

The parameters for paginating the results, specifying the index and number of items to return. If no parameters are supplied, the request will return the default number of items beginning with first item.

Return Value

An SKRequest instance with which to perform the API request.


                    
                    
                    getNewReleases(page:completion:)

Gets a list of new album releases featured by Spotify (for example, those shown on a Spotify player’s Browse tab).

Declaration

Swift

public func getNewReleases(page: Pagination? = nil, completion handler: @escaping (Page<SKAlbum>?, Error?) -> Void)

Parameters

`page`	The parameters for paginating the results, specifying the index and number of items to return. If no parameters are supplied, the request will return the default number of items beginning with first item. The default value is `nil`.
`handler`	The callback handler for the request. The parameters for this handler are: `albums`: A paginated collection of newly released albums. `error`: An error identifying if and why the request failed, or `nil` if the request was successful.

Get a List of Categories


                    
                    
                    makeCategoriesRequest(page:)

Creates and returns the request used to get a list of categories.

Note

If a catalog locale has not been specified (i.e., locale is set to nil), or if the specified language is not available, all strings will be returned in the Spotify default language (American English).

Declaration

Swift

public func makeCategoriesRequest(page: Pagination?) -> SKRequest

Parameters


                                page

The parameters for paginating the results, specifying the index and number of items to return. If no parameters are supplied, the request will return the default number of items beginning with first item.

Return Value

An SKRequest instance with which to perform the API request.


                    
                    
                    getCategories(page:completion:)

Gets a list of categories used to tag items in Spotify (for example, those shown on a Spotify player’s Browse tab).

Note

If a catalog locale has not been specified (i.e., locale is set to nil), or if the specified language is not available, all strings will be returned in the Spotify default language (American English).

Declaration

Swift

public func getCategories(page: Pagination? = nil, completion handler: @escaping (Page<SKCategory>?, Error?) -> Void)

Parameters

`page`	The parameters for paginating the results, specifying the index and number of items to return. If no parameters are supplied, the request will return the default number of items beginning with first item. The default value is `nil`.
`handler`	The callback handler for the request. The parameters for this handler are: `categories`: A paginated collection of available Spotify categories. `error`: An error identifying if and why the request failed, or `nil` if the request was successful.

Get a Category


                    
                    
                    makeCategoryRequest(id:)

Creates and returns the request used to get a single category.

Note

If a catalog locale has not been specified (i.e., locale is set to nil), or if the specified language is not available, all strings will be returned in the Spotify default language (American English).

Declaration

Swift

public func makeCategoryRequest(id: String) -> SKRequest

Parameters

`id`	The Spotify category ID for the category.

Return Value

An SKRequest instance with which to perform the API request.


                    
                    
                    getCategory(withID:completion:)

Gets a single category used to tag items in Spotify (for example, those shown on a Spotify player’s Browse tab).

Note

If a catalog locale has not been specified (i.e., locale is set to nil), or if the specified language is not available, all strings will be returned in the Spotify default language (American English).

Declaration

Swift

public func getCategory(withID id: String, completion handler: @escaping (SKCategory?, Error?) -> Void)

Parameters

`id`	id: The Spotify category ID for the category.
`handler`	The callback handler for the request. The parameters for this handler are: `category`: The requested category, if available. `error`: An error identifying if and why the request failed, or `nil` if the request was successful.

Get Available Genre Seeds

makeAvailableGenresRequest()
Creates and returns the request used to get available genre seeds for recommendations.
Declaration
Swift

public func makeAvailableGenresRequest() -> SKRequest
Return Value

An SKRequest instance with which to perform the API request.


                    
                    
                    getAvailableGenres(completion:)

Gets a list of available genre seeds used for recommendations.

Declaration

Swift

public func getAvailableGenres(completion handler: @escaping ([String]?, Error?) -> Void)

Parameters


                                handler

The callback handler for the request. The parameters for this handler are:

genres: The list of available genres.
error: An error identifying if and why the request failed, or nil if the request was successful.

Get Recommendations


                    
                    
                    makeRecommendationsRequest(genres:artists:tracks:attributes:limit:)

Creates and returns the request used to get recommendations based on seed genres, artists, and tracks.

Recommendations are generated based on the available information for a given seed entity and matched against similar artists and tracks. If there is sufficient information about the provided seeds, a list of tracks will be returned together with pool size details.

Note

For each request, you may provide up to five seed items comprised of any combination of genres, artists, and tracks. If more than five seed items are provided, the request will result in an error.

In cases where seed artists and tracks are very new or obscure, the request may not have enough data to generate a list of tracks.

Declaration

Swift

public func makeRecommendationsRequest<T, U, V>(genres: T, artists: U, tracks: V, attributes: Set<SKTrackAttribute>, limit: Int?) -> SKRequest where T : Collection, U : Collection, V : Collection, T.Element : StringProtocol, U.Element == SKArtist, V.Element : Track

Parameters

`genres`	A list of seed genres. For possible values, use the `getAvailableGenres` method to retrieve a list of genres available as seeds for this request.
`artists`	A list of seed artists.
`tracks`	A list of seed tracks.
`attributes`	A list of tunable track attributes by which to filter results. Each attribute allows you to specify a minimum value, maximum value, and target value.
`limit`	The target size of the results.

Return Value

An SKRequest instance with which to perform the API request.


                    
                    
                    getRecommendationsBasedOn(genres:artists:tracks:filteredBy:limit:completion:)

Gets recommendations based on seed genres, artists, and tracks.

Recommendations are generated based on the available information for a given seed entity and matched against similar artists and tracks. If there is sufficient information about the provided seeds, a list of tracks will be returned together with pool size details.

Note

For each request, you may provide up to five seed items comprised of any combination of genres, artists, and tracks. If more than five seed items are provided, the request will result in an error.

In cases where seed artists and tracks are very new or obscure, the request may not have enough data to generate a list of tracks.

Declaration

Swift

public func getRecommendationsBasedOn<T: Collection, U: Collection, V: Collection>(genres: T, artists: U, tracks: V, filteredBy attributes: Set<SKTrackAttribute> = [], limit: Int? = nil, completion handler: @escaping (SKRecommendations?, Error?) -> Void) where T.Element: StringProtocol, U.Element == SKArtist, V.Element: Track

Parameters

`genres`	A list of seed genres. For possible values, use the `getAvailableGenres` method to retrieve a list of genres available as seeds for this request.
`artists`	A list of seed artists.
`tracks`	A list of seed tracks.
`attributes`	A list of tunable track attributes by which to filter results. Each attribute allows you to specify a minimum value, maximum value, and target value.
`limit`	The target size of the results.
`handler`	The callback handler for the request. The parameters for this handler are: `recommendations`: An `SKRecommendations` instance, which contains an array of tracks accompanied by the seeds from which the tracks are returned. `error`: An error identifying if and why the request failed, or `nil` if the request was successful.

Search


                    
                    
                    makeSearchRequest(types:keywords:alternate:unwanted:inOrder:filters:page:)

Creates and returns the request used to search the Spotify catalog.

Declaration

Swift

public func makeSearchRequest(types: Set<SKSearchResultType>,
                              keywords: String,
                              alternate: String?,
                              unwanted: String?,
                              inOrder: Bool,
                              filters: Set<SKSearchFieldFilter>,
                              page: Pagination?) -> SKRequest

Parameters

`types`	An array identifying the types of items requested by the search. Possible values are `.album`, `.artist`, `.track`, and `.playlist`. The static constant `.all` can also be used to represent an array containing all search result types.
`keywords`	The search term against which to match results. Note: Keyword matching is not case-sensitive.
`alternate`	An alternate search term used to broaden the search. If no alternate keywords are needed, set this parameter to `nil`.
`unwanted`	Unwanted keywords to exclude from the search. If no unwanted keywords are needed, set this parameter to `nil`.
`inOrder`	When `false`, keywords will be matched in any order; when `true`, the search will maintain exact keyword order.
`filters`	A list of field filters by which to narrow the search. For available filters, see `SKSearchFieldFilter`. If no filters are needed, set this parameter to an empty array.
`page`	The parameters for paginating the results, specifying the index and number of items to return. If no parameters are supplied, the request will return the default number of items beginning with first item.

Return Value

An SKRequest instance with which to perform the API request.


                    
                    
                    search(for:matching:or:excluding:inOrder:filteredBy:page:completion:)

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

Declaration

Swift

public func search(for types: Set<SKSearchResultType>,
                   matching keywords: String,
                   or alternate: String? = nil,
                   excluding unwanted: String? = nil,
                   inOrder: Bool = false,
                   filteredBy filters: Set<SKSearchFieldFilter> = [],
                   page: Pagination? = nil,
                   completion handler: @escaping (SKSearchResults?, Error?) -> Void)

Parameters

`types`	An array identifying the types of items requested by the search. Possible values are `.album`, `.artist`, `.track`, and `.playlist`. The static constant `.all` can also be used to represent an array containing all search result types.
`keywords`	The search term against which to match results. Note: Keyword matching is not case-sensitive.
`alternate`	An alternate search term used to broaden the search. The default value is an empty string.
`unwanted`	Unwanted keywords to exclude from the search. The default value is an empty string.
`inOrder`	When `false`, keywords will be matched in any order; when `true`, the search will maintain exact keyword order. The default value is `false`.
`filters`	A list of field filters by which to narrow the search. For available filters, see `SKSearchFieldFilter`. The default value is an empty array.
`page`	The parameters for paginating the results, specifying the index and number of items to return. If no parameters are supplied, the request will return the default number of items beginning with first item. The default value is `nil`.
`handler`	The callback handler for this request. The parameters for this handler are: `results`: An `SKSearchResults` instance containing paged results for any albums, artists, tracks, or playlists returned by the search. `error`: An error identifying if and why the request failed, or `nil` if the request was successful.