KKBOXOpenAPI Class Reference


                    
                    
                    init(clientID:secret:scope:)

Create an instance of KKBOXOpenAPI by giving a client ID and secret.

To obtain a client ID and secret, visit KKBOX’s Developer Site .

Declaration

Swift

public init(clientID: String, secret: String, scope: KKScope = .none)

Parameters

`clientID`	A valid client ID
`secret`	A valid client Secret
`scope`	Scope of the client.

requestScope
Scope of the client. It is KKScope.none by default.
Declaration
Swift

public var requestScope: KKScope


                    
                    
                    accessToken

The current access token.

Declaration

Swift

public private(set) var accessToken: KKAccessToken? { get set }

isLoggedIn
MARK: - Authentication If the user has logged-in into KKBOX or not.
Declaration
Swift

public var isLoggedIn: Bool { get }
logout()
Remove current access token.
Declaration
Swift

public func logout()


                    
                    
                    fetchAccessTokenByClientCredential(callback:)

Fetch an access token by passing client credential.

Throws

KKBOXOpenAPIError.failedToCreateClientCredential

Declaration

Swift

public func fetchAccessTokenByClientCredential(callback: @escaping (_ result: KKAPIResult<KKAccessToken>) -> ()) throws -> URLSessionTask

Parameters

`callback`	The callback closure.
`result`	The access token.

Return Value

A URLSessionTask that you can use it to cancel current fetch.

Tracks


                    
                    
                    fetch(track:territory:callback:)

Fetch a song track by giving a song track ID.

See API reference.

Throws

KKBOXOpenAPIError.requireAccessToken.

Declaration

Swift

public func fetch(track ID: String, territory: KKTerritory = .taiwan, callback: @escaping (_ result: KKAPIResult<KKTrackInfo>) -> ()) throws -> URLSessionTask

Parameters

`ID`	ID of the track.
`territory`	The Territory
`callback`	The callback closure.
`result`	The result that contains the song track info.

Return Value

A URLSessionTask that you can use it to cancel current fetch.

Albums


                    
                    
                    fetch(album:territory:callback:)

Fetch an album by giving an album ID.

See API reference.

Throws

KKBOXOpenAPIError.requireAccessToken.

Declaration

Swift

public func fetch(album ID: String, territory: KKTerritory = .taiwan, callback: @escaping (_ result: KKAPIResult<KKAlbumInfo>) -> ()) throws -> URLSessionTask

Parameters

`ID`	ID of the album.
`territory`	The Territory.
`callback`	The callback closure.
`result`	The result that contains the album info.

Return Value

A URLSessionTask that you can use it to cancel current fetch.


                    
                    
                    fetch(tracksInAlbum:territory:callback:)

Fetch tracks contained in an album.

See API reference.

Throws

KKBOXOpenAPIError.requireAccessToken.

Declaration

Swift

public func fetch(tracksInAlbum ID: String, territory: KKTerritory = .taiwan, callback: @escaping (_ result: KKAPIResult<KKTrackList>) -> ()) throws -> URLSessionTask

Parameters

`ID`	ID of the album.
`territory`	The Territory.
`callback`	The callback closure.
`result`	The result that contains tracks of the album.

Return Value

A URLSessionTask that you can use it to cancel current fetch.

Artist


                    
                    
                    fetch(artist:territory:callback:)

Fetch the profile by giving an artist ID.

See API reference.

Throws

KKBOXOpenAPIError.requireAccessToken.

Declaration

Swift

public func fetch(artist ID: String, territory: KKTerritory = .taiwan, callback: @escaping (_ result: KKAPIResult<KKArtistInfo>) -> ()) throws -> URLSessionTask

Parameters

`ID`	ID of the artist.
`territory`	The Territory.
`callback`	The callback closure.
`result`	The result that contains profile of the artist.

Return Value

A URLSessionTask that you can use it to cancel current fetch.


                    
                    
                    fetch(albumsBelongToArtist:territory:offset:limit:callback:)

Fetch albums of an artist.

See API reference.

Throws

KKBOXOpenAPIError.requireAccessToken.

Declaration

Swift

public func fetch(albumsBelongToArtist ID: String, territory: KKTerritory = .taiwan, offset: Int = 0, limit: Int = 200, callback: @escaping (_ result: KKAPIResult<KKAlbumList>) -> ()) throws -> URLSessionTask

Parameters

`ID`	ID of the artist.
`territory`	The Territory.
`offset`	The offset. 0 by default.
`limit`	The limit. 200 by default.
`callback`	The callback closure.
`result`	The result that contains albums of the artist.

Return Value

A URLSessionTask that you can use it to cancel current fetch.


                    
                    
                    fetch(topTracksOfArtist:territory:offset:limit:callback:)

Fetch top tracks of an artist.

See API reference.

Throws

KKBOXOpenAPIError.requireAccessToken.

Declaration

Swift

public func fetch(topTracksOfArtist ID: String, territory: KKTerritory = .taiwan, offset: Int = 0, limit: Int = 200, callback: @escaping (_ result: KKAPIResult<KKTrackList>) -> ()) throws -> URLSessionTask

Parameters

`ID`	ID of the artist.
`territory`	The Territory.
`offset`	The offset. 0 by default.
`limit`	The limit. 200 by default.
`callback`	The callback closure.
`result`	The result that contains top tracks of the artist.

Return Value

A URLSessionTask that you can use it to cancel current fetch.


                    
                    
                    fetch(relatedArtistsOfArtist:territory:offset:limit:callback:)

Fetch related artists of an artist.

See API reference.

Throws

KKBOXOpenAPIError.requireAccessToken.

Declaration

Swift

public func fetch(relatedArtistsOfArtist ID: String, territory: KKTerritory = .taiwan, offset: Int = 0, limit: Int = 20, callback: @escaping (_ result: KKAPIResult<KKArtistList>) -> ()) throws -> URLSessionTask

Parameters

`ID`	ID of the artist.
`territory`	The Territory.
`offset`	The offset. 0 by default.
`limit`	The limit. 20 by default.
`callback`	The callback closure.
`result`	The result that contains related artists of the artist.

Return Value

A URLSessionTask that you can use it to cancel current fetch.

Shared Playlists


                    
                    
                    fetch(playlist:territory:callback:)

Fetch a playlist’s metadata and tracks by giving the playlist ID

See API reference.

Throws

KKBOXOpenAPIError.requireAccessToken.

Declaration

Swift

public func fetch(playlist ID: String, territory: KKTerritory = .taiwan, callback: @escaping (_ result: KKAPIResult<KKPlaylistInfo>) -> ()) throws -> URLSessionTask

Parameters

`ID`	The playlist ID.
`territory`	The Territory.
`callback`	The callback closure.
`result`	The result that contains the metadata and tracks of the playlist.

Return Value

A URLSessionTask that you can use it to cancel current fetch.


                    
                    
                    fetch(tracksInPlaylist:territory:offset:limit:callback:)

Fetch tracks contained in a playlist.

See API reference.

Throws

KKBOXOpenAPIError.requireAccessToken.

Declaration

Swift

public func fetch(tracksInPlaylist ID: String, territory: KKTerritory = .taiwan, offset: Int = 0, limit: Int = 20, callback: @escaping (_ result: KKAPIResult<KKTrackList>) -> ()) throws -> URLSessionTask

Parameters

`ID`	The playlist ID.
`territory`	The Territory.
`offset`	The offset. 0 by default.
`limit`	The limit. 20 by default.
`callback`	The callback closure.
`result`	The result that contains the metadata of the playlist.

Return Value

A URLSessionTask that you can use it to cancel current fetch.

Featured Playlists


                    
                    
                    fetchFeaturedPlaylists(territory:offset:limit:callback:)

Fetch the featured playlists.

See API reference.

Throws

KKBOXOpenAPIError.requireAccessToken.

Declaration

Swift

public func fetchFeaturedPlaylists(territory: KKTerritory = .taiwan, offset: Int = 0, limit: Int = 100, callback: @escaping (_ result: KKAPIResult<KKPlaylistList>) -> ()) throws -> URLSessionTask

Parameters

`territory`	The Territory.
`offset`	The offset. 0 by default.
`limit`	The limit. 100 by default.
`callback`	The callback closure.
`result`	The result that contains the featured playlists.

Return Value

A URLSessionTask that you can use it to cancel current fetch.

New-Hits Playlists


                    
                    
                    fetchNewHitsPlaylists(territory:offset:limit:callback:)

Fetch the New-Hits playlists.

See API reference.

Throws

KKBOXOpenAPIError.requireAccessToken.

Declaration

Swift

public func fetchNewHitsPlaylists(territory: KKTerritory = .taiwan, offset: Int = 0, limit: Int = 10, callback: @escaping (_ result: KKAPIResult<KKPlaylistList>) -> ()) throws -> URLSessionTask

Parameters

`territory`	The Territory.
`offset`	The offset. 0 by default.
`limit`	The limit. 10 by default.
`callback`	The callback closure.
`result`	The result that contains the New-Hits playlists.

Return Value

A URLSessionTask that you can use it to cancel current fetch.

Featured Playlists Categories


                    
                    
                    fetchFeaturedPlaylistCategories(territory:offset:limit:callback:)

Fetch featured playlist categories.

See API reference.

Throws

KKBOXOpenAPIError.requireAccessToken.

Declaration

Swift

public func fetchFeaturedPlaylistCategories(territory: KKTerritory = .taiwan, offset: Int = 0, limit: Int = 100, callback: @escaping (_ result: KKAPIResult<KKFeaturedPlaylistCategoryList>) -> ()) throws -> URLSessionTask

Parameters

`territory`	The Territory.
`offset`	The offset. 0 by default.
`limit`	The limit. 100 by default.
`callback`	The callback closure.
`result`	The result that contains featured playlist categories.

Return Value

A URLSessionTask that you can use it to cancel current fetch.


                    
                    
                    fetchFeaturedPlaylist(inCategory:territory:offset:limit:callback:)

Fetch featured playlists in a category.

See API reference.

Throws

KKBOXOpenAPIError.requireAccessToken.

Declaration

Swift

public func fetchFeaturedPlaylist(inCategory ID: String, territory: KKTerritory = .taiwan, offset: Int = 0, limit: Int = 100, callback: @escaping (_ result: KKAPIResult<KKFeaturedPlaylistCategory>) -> ()) throws -> URLSessionTask

Parameters

`ID`	The category ID.
`territory`	The Territory.
`offset`	The offset. 0 by default.
`limit`	The limit. 100 by default.
`callback`	The callback closure.
`result`	The result that contains featured playlists.

Return Value

A URLSessionTask that you can use it to cancel current fetch.

Mood Radio Stations


                    
                    
                    fetchMoodStations(territory:offset:limit:callback:)

Fetch mood station categories.

See API reference.

Throws

KKBOXOpenAPIError.requireAccessToken.

Declaration

Swift

public func fetchMoodStations(territory: KKTerritory = .taiwan, offset: Int = 0, limit: Int = 100, callback: @escaping (_ result: KKAPIResult<KKRadioStationList>) -> ()) throws -> URLSessionTask

Parameters

`territory`	The Territory.
`offset`	The offset. 0 by default.
`limit`	The limit. 100 by default.
`callback`	The callback closure.
`result`	The result that contains the mood station categories.

Return Value

A URLSessionTask that you can use it to cancel current fetch.


                    
                    
                    fetch(tracksInMoodStation:territory:offset:limit:callback:)

Fetch tracks in a mood radio station.

See API reference.

Throws

KKBOXOpenAPIError.requireAccessToken.

Declaration

Swift

public func fetch(tracksInMoodStation ID: String, territory: KKTerritory = .taiwan, offset: Int = 0, limit: Int = 100, callback: @escaping (_ result: KKAPIResult<KKRadioStation>) -> ()) throws -> URLSessionTask

Parameters

`ID`	Mood station ID
`territory`	The Territory.
`offset`	The offset. 0 by default.
`limit`	The limit. 100 by default.
`callback`	The callback closure.
`result`	The result that contains the tracks.

Return Value

A URLSessionTask that you can use it to cancel current fetch.

Genre Radio Stations


                    
                    
                    fetchGenreStations(territory:offset:limit:callback:)

Fetch genre station categories.

See API reference.

Throws

KKBOXOpenAPIError.requireAccessToken.

Declaration

Swift

public func fetchGenreStations(territory: KKTerritory = .taiwan, offset: Int = 0, limit: Int = 100, callback: @escaping (_ result: KKAPIResult<KKRadioStationList>) -> ()) throws -> URLSessionTask

Parameters

`territory`	The Territory.
`offset`	The offset. 0 by default.
`limit`	The limit. 100 by default.
`callback`	The callback closure.
`result`	The result that contains the mood genre categories.

Return Value

A URLSessionTask that you can use it to cancel current fetch.


                    
                    
                    fetch(tracksInGenreStation:territory:offset:limit:callback:)

Fetch tracks in a genre radio station.

See API reference.

Throws

KKBOXOpenAPIError.requireAccessToken.

Declaration

Swift

public func fetch(tracksInGenreStation ID: String, territory: KKTerritory = .taiwan, offset: Int = 0, limit: Int = 100, callback: @escaping (_ result: KKAPIResult<KKRadioStation>) -> ()) throws -> URLSessionTask

Parameters

`ID`	Genre station ID
`territory`	The Territory.
`offset`	The offset. 0 by default.
`limit`	The limit. 100 by default.
`callback`	The callback closure.
`result`	The result that contains the tracks.

Return Value

A URLSessionTask that you can use it to cancel current fetch.

New Released Albums


                    
                    
                    fetchNewReleaseAlbumsCategories(territory:offset:limit:callback:)

Fetch the categories of the new released albums.

See API reference.

Throws

KKBOXOpenAPIError.requireAccessToken.

Declaration

Swift

public func fetchNewReleaseAlbumsCategories(territory: KKTerritory = .taiwan, offset: Int = 0, limit: Int = 100, callback: @escaping (_ result: KKAPIResult<KKNewReleasedAlbumsCategoryList>) -> ()) throws -> URLSessionTask

Parameters

`territory`	The Territory.
`offset`	The offset. 0 by default.
`limit`	The limit. 100 by default.
`callback`	The callback closure.
`result`	The result that contains the categories.

Return Value

A URLSessionTask that you can use it to cancel current fetch.


                    
                    
                    fetch(newReleasedAlbumsUnderCategory:territory:offset:limit:callback:)

Fetch albums in a given new released albums category.

See API reference.

Throws

KKBOXOpenAPIError.requireAccessToken.

Declaration

Swift

public func fetch(newReleasedAlbumsUnderCategory ID: String, territory: KKTerritory = .taiwan, offset: Int = 0, limit: Int = 100, callback: @escaping (_ result: KKAPIResult<KKNewReleasedAlbumsCategory>) -> ()) throws -> URLSessionTask

Parameters

`ID`	The category ID.
`territory`	The Territory.
`offset`	The offset. 0 by default.
`limit`	The limit. 100 by default.
`callback`	The callback closure.
`result`	The result that contains the albums.

Return Value

A URLSessionTask that you can use it to cancel current fetch.

Charts


                    
                    
                    fetchCharts(territory:offset:limit:callback:)

Fetch charts.

See API reference.

Throws

KKBOXOpenAPIError.requireAccessToken.

Declaration

Swift

public func fetchCharts(territory: KKTerritory = .taiwan, offset: Int = 0, limit: Int = 50, callback: @escaping (_ result: KKAPIResult<KKPlaylistList>) -> ()) throws -> URLSessionTask

Parameters

`territory`	The Territory.
`offset`	The offset. 0 by default.
`limit`	The limit. 50 by default.
`callback`	The callback closure.
`result`	The result that contains the charts.

Return Value

A URLSessionTask that you can use it to cancel current fetch.

Search


                    
                    
                    search(with:types:territory:offset:limit:callback:)

Search in KKBOX’s music library.

See API reference.

Throws

KKBOXOpenAPIError.requireAccessToken.

Declaration

Swift

public func search(with keyword: String, types: KKSearchType, territory: KKTerritory = .taiwan, offset: Int = 0, limit: Int = 50, callback: @escaping (_ result: KKAPIResult<KKSearchResults>) -> ()) throws -> URLSessionTask

Parameters

`keyword`	The search keyword.
`types`	Artists, albums, tracks or playlists.
`territory`	The territory.
`offset`	The offset. 0 by default.
`limit`	The limit. 50 by default.
`callback`	The callback closure.
`result`	The result that contains search results.

Return Value

A URLSessionTask that you can use it to cancel current fetch.