KKBOXOpenAPI

@interface KKBOXOpenAPI : NSObject

The class helps to access KKBOX’s Open API on Apple platforms such as iOS, macOS, watchOS and tvOS.

To start accessing KKBOX’s API, you need to register your self to obtain a valid client ID(API Key) and shared secret, then you can use your client ID and secret to initialize an instance of the class. To obtain a client ID, please visit https://developer.kkbox.com/.

  • Create a new KKBOXOpenAPI instance. (Default scope is all)

    Declaration

    Objective-C

    - (nonnull instancetype)initWithClientID:(nonnull NSString *)clientID
                                  secret:(nonnull NSString *)secret;

    Swift

    init(clientID: String, secret: String)

    Parameters

    clientID

    the API key
    secret

    the API secret

    Return Value

    A KKBOXOpenAPI instance

    Show on GitHub

  • Create a new KKBOXOpenAPI instance.

    Declaration

    Objective-C

    - (nonnull instancetype)initWithClientID:(nonnull NSString *)clientID
                                  secret:(nonnull NSString *)secret
                                   scope:(KKScope)scope;

    Swift

    init(clientID: String, secret: String, scope: KKScope)

    Parameters

    clientID

    the API key
    secret

    the API secret
    scope

    the OAuth permission scope

    Return Value

    A KKBOXOpenAPI instance

    Show on GitHub

  • Clear existing access token.

    Declaration

    Objective-C

    - (void)logout;

    Swift

    func logout()
    Show on GitHub

  • The current access token.

    Declaration

    Objective-C

    @property (readonly, strong, nonatomic, nullable) KKAccessToken *accessToken;

    Swift

    var accessToken: KKAccessToken? { get }
    Show on GitHub

  • If there is a valid access token.

    Declaration

    Objective-C

    @property (readonly, assign, atomic) BOOL loggedIn;

    Swift

    var loggedIn: Bool { get }
    Show on GitHub

LoginWithClientCredential

  • To start using KKBOx’s Open API, you need to log-in in to KKBOX at first. You can generate a client credential to fetch an access token to let KKBOX identify you. It allows you to access public data from KKBOX such as public albums, playlists and so on.

    Declaration

    Objective-C

    - (nonnull NSURLSessionDataTask *)
    fetchAccessTokenByClientCredentialWithCallback:
        (nonnull KKBOXOpenAPILoginCallback)callback;

    Swift

    func fetchAccessTokenByClientCredential(callback: @escaping KKBOXOpenAPILoginCallback) -> URLSessionDataTask

    Parameters

    callback

    the callback block.

    Return Value

    an NSURLSessionDataTask object that allow you to cancel the task.

    Show on GitHub

Song Tracks

  • Fetch the detailed information of a song track.

    See https://docs-en.kkbox.codes/v1.1/reference#tracks_track_id.

    Declaration

    Objective-C

    - (nonnull NSURLSessionDataTask *)
    fetchTrackWithTrackID:(nonnull NSString *)trackID
                territory:(KKTerritoryCode)territory
                 callback:(nonnull void (^)(KKTrackInfo *_Nullable,
                                            NSError *_Nullable))callback;

    Swift

    func fetchTrack(withTrackID trackID: String, territory: KKTerritoryCode, callback: @escaping (KKTrackInfo?, Error?) -> Void) -> URLSessionDataTask

    Parameters

    trackID

    the ID of the song track
    territory

    the given territory. The displayed information of a song track may differ in different territories.
    callback

    the callback block

    Return Value

    an NSURLSessionDataTask object that allow you to cancel the task.

    Show on GitHub

Album

  • Fetch the information of a given album.

    See https://docs-en.kkbox.codes/v1.1/reference#albums_album_id.

    Declaration

    Objective-C

    - (nonnull NSURLSessionDataTask *)
    fetchAlbumWithAlbumID:(nonnull NSString *)albumID
                territory:(KKTerritoryCode)territory
                 callback:(nonnull void (^)(KKAlbumInfo *_Nullable,
                                            NSError *_Nullable))callback;

    Swift

    func fetchAlbum(withAlbumID albumID: String, territory: KKTerritoryCode, callback: @escaping (KKAlbumInfo?, Error?) -> Void) -> URLSessionDataTask

    Parameters

    albumID

    the given album ID
    territory

    the given territory
    callback

    the callback block

    Return Value

    an NSURLSessionDataTask object that allow you to cancel the task.

    Show on GitHub

  • Fetch the song tracks contained in a given album.

    See https://docs-en.kkbox.codes/v1.1/reference#albums_album_id_tracks.

    Declaration

    Objective-C

    - (nonnull NSURLSessionDataTask *)
    fetchTracksWithAlbumID:(nonnull NSString *)albumID
                 territory:(KKTerritoryCode)territory
                  callback:(nonnull void (^)(NSArray<KKTrackInfo *> *_Nullable,
                                             KKPagingInfo *_Nullable,
                                             KKSummary *_Nullable,
                                             NSError *_Nullable))callback;

    Swift

    func fetchTracks(withAlbumID albumID: String, territory: KKTerritoryCode, callback: @escaping ([KKTrackInfo]?, KKPagingInfo?, KKSummary?, Error?) -> Void) -> URLSessionDataTask

    Parameters

    albumID

    the given album ID
    territory

    the given territory
    callback

    the callback block

    Return Value

    an NSURLSessionDataTask object that allow you to cancel the task.

    Show on GitHub

Artists

  • Fetch the detailed profile of an artist.

    See https://docs-en.kkbox.codes/v1.1/reference#artists_artist_id.

    Declaration

    Objective-C

    - (nonnull NSURLSessionDataTask *)
    fetchArtistInfoWithArtistID:(nonnull NSString *)artistID
                      territory:(KKTerritoryCode)territory
                       callback:(nonnull void (^)(KKArtistInfo *_Nullable,
                                                  NSError *_Nullable))callback;

    Swift

    func fetchArtistInfo(withArtistID artistID: String, territory: KKTerritoryCode, callback: @escaping (KKArtistInfo?, Error?) -> Void) -> URLSessionDataTask

    Parameters

    artistID

    the ID of the artist
    territory

    the given territory. The displayed information of an artist may differ in different territories.
    callback

    the callback block

    Return Value

    an NSURLSessionDataTask object that allow you to cancel the task.

    Show on GitHub

  • Fetch the list of the albums belong to an artist.

    See https://docs-en.kkbox.codes/v1.1/reference#artists_artist_id_albums

    Declaration

    Objective-C

    - (nonnull NSURLSessionDataTask *)
    fetchAlbumsBelongToArtistID:(nonnull NSString *)artistID
                      territory:(KKTerritoryCode)territory
                       callback:
                           (nonnull void (^)(NSArray<KKAlbumInfo *> *_Nullable,
                                             KKPagingInfo *_Nullable,
                                             KKSummary *_Nullable,
                                             NSError *_Nullable))callback;

    Swift

    func fetchAlbumsBelong(toArtistID artistID: String, territory: KKTerritoryCode, callback: @escaping ([KKAlbumInfo]?, KKPagingInfo?, KKSummary?, Error?) -> Void) -> URLSessionDataTask

    Parameters

    artistID

    the ID of the artist
    territory

    the given territory. The albums list may differ in different territories since KKBOX may not be licensed to distribute music content in all territories.
    callback

    the callback block

    Return Value

    an NSURLSessionDataTask object that allow you to cancel the task.

    Show on GitHub

  • Fetch the list of the albums belong to an artist.

    See https://docs-en.kkbox.codes/v1.1/reference#artists_artist_id_albums

    Declaration

    Objective-C

    - (nonnull NSURLSessionDataTask *)
    fetchAlbumsBelongToArtistID:(nonnull NSString *)artistID
                      territory:(KKTerritoryCode)territory
                         offset:(NSInteger)offset
                          limit:(NSInteger)limit
                       callback:
                           (nonnull void (^)(NSArray<KKAlbumInfo *> *_Nullable,
                                             KKPagingInfo *_Nullable,
                                             KKSummary *_Nullable,
                                             NSError *_Nullable))callback;

    Swift

    func fetchAlbumsBelong(toArtistID artistID: String, territory: KKTerritoryCode, offset: Int, limit: Int, callback: @escaping ([KKAlbumInfo]?, KKPagingInfo?, KKSummary?, Error?) -> Void) -> URLSessionDataTask

    Parameters

    artistID

    the ID of the artist
    territory

    the given territory. The albums list may differ in different territories since KKBOX may not be licensed to distribute music content in all territories.
    offset

    the offset
    limit

    the limit of response
    callback

    the callback block

    Return Value

    an NSURLSessionDataTask object that allow you to cancel the task.

    Show on GitHub

  • Fetch the top tracks of an artist.

    See https://docs-en.kkbox.codes/v1.1/reference#artists_artist_id_top-tracks.

    Declaration

    Objective-C

    - (nonnull NSURLSessionDataTask *)
    fetchTopTracksWithArtistID:(nonnull NSString *)artistID
                     territory:(KKTerritoryCode)territory
                      callback:
                          (nonnull void (^)(NSArray<KKTrackInfo *> *_Nullable,
                                            KKPagingInfo *_Nullable,
                                            KKSummary *_Nullable,
                                            NSError *_Nullable))callback;

    Swift

    func fetchTopTracks(withArtistID artistID: String, territory: KKTerritoryCode, callback: @escaping ([KKTrackInfo]?, KKPagingInfo?, KKSummary?, Error?) -> Void) -> URLSessionDataTask

    Parameters

    artistID

    the ID of the artist
    territory

    the given territory. The displayed information of an artist may differ in different territories.
    callback

    the callback block

    Return Value

    an NSURLSessionDataTask object that allow you to cancel the task.

    Show on GitHub

  • Fetch the top tracks of an artist.

    See https://docs-en.kkbox.codes/v1.1/reference#artists_artist_id_top-tracks.

    Declaration

    Objective-C

    - (nonnull NSURLSessionDataTask *)
    fetchTopTracksWithArtistID:(nonnull NSString *)artistID
                     territory:(KKTerritoryCode)territory
                        offset:(NSInteger)offset
                         limit:(NSInteger)limit
                      callback:
                          (nonnull void (^)(NSArray<KKTrackInfo *> *_Nullable,
                                            KKPagingInfo *_Nullable,
                                            KKSummary *_Nullable,
                                            NSError *_Nullable))callback;

    Swift

    func fetchTopTracks(withArtistID artistID: String, territory: KKTerritoryCode, offset: Int, limit: Int, callback: @escaping ([KKTrackInfo]?, KKPagingInfo?, KKSummary?, Error?) -> Void) -> URLSessionDataTask

    Parameters

    artistID

    the ID of the artist
    territory

    the given territory. The displayed information of an artist may differ in different territories.
    offset

    the offset
    limit

    the limit of response
    callback

    the callback block

    Return Value

    an NSURLSessionDataTask object that allow you to cancel the task.

    Show on GitHub

  • Fetch related artists of an artist.

    See https://docs-en.kkbox.codes/v1.1/reference#artists_artist_id_related-artists.

    Declaration

    Objective-C

    - (nonnull NSURLSessionDataTask *)
    fetchRelatedArtistsWithArtistID:(nonnull NSString *)artistID
                          territory:(KKTerritoryCode)territory
                           callback:(nonnull void (^)(
                                        NSArray<KKArtistInfo *> *_Nullable,
                                        KKPagingInfo *_Nullable,
                                        KKSummary *_Nullable,
                                        NSError *_Nullable))callback;

    Swift

    func fetchRelatedArtists(withArtistID artistID: String, territory: KKTerritoryCode, callback: @escaping ([KKArtistInfo]?, KKPagingInfo?, KKSummary?, Error?) -> Void) -> URLSessionDataTask

    Parameters

    artistID

    the ID of the artist
    territory

    the given territory. The displayed information of an artist may differ in different territories.
    callback

    the callback block

    Return Value

    an NSURLSessionDataTask object that allow you to cancel the task.

    Show on GitHub

  • Fetch related artists of an artist.

    See https://docs-en.kkbox.codes/v1.1/reference#artists_artist_id_related-artists.

    Declaration

    Objective-C

    - (nonnull NSURLSessionDataTask *)
    fetchRelatedArtistsWithArtistID:(nonnull NSString *)artistID
                          territory:(KKTerritoryCode)territory
                             offset:(NSInteger)offset
                              limit:(NSInteger)limit
                           callback:(nonnull void (^)(
                                        NSArray<KKArtistInfo *> *_Nullable,
                                        KKPagingInfo *_Nullable,
                                        KKSummary *_Nullable,
                                        NSError *_Nullable))callback;

    Swift

    func fetchRelatedArtists(withArtistID artistID: String, territory: KKTerritoryCode, offset: Int, limit: Int, callback: @escaping ([KKArtistInfo]?, KKPagingInfo?, KKSummary?, Error?) -> Void) -> URLSessionDataTask

    Parameters

    artistID

    the ID of the artist
    territory

    the given territory. The displayed information of an artist may differ in different territories.
    offset

    the offset
    limit

    the limit of response
    callback

    the callback block

    Return Value

    an NSURLSessionDataTask object that allow you to cancel the task.

    Show on GitHub

Shared Playlists

  • Fetches information and song tracks of a given playlist.

    See https://docs-en.kkbox.codes/v1.1/reference#shared-playlists_playlist_id.

    Declaration

    Objective-C

    - (nonnull NSURLSessionDataTask *)
    fetchPlaylistWithPlaylistID:(nonnull NSString *)playlistID
                      territory:(KKTerritoryCode)territory
                       callback:(nonnull void (^)(KKPlaylistInfo *_Nullable,
                                                  KKPagingInfo *_Nullable,
                                                  KKSummary *_Nullable,
                                                  NSError *_Nullable))callback;

    Swift

    func fetchPlaylist(withPlaylistID playlistID: String, territory: KKTerritoryCode, callback: @escaping (KKPlaylistInfo?, KKPagingInfo?, KKSummary?, Error?) -> Void) -> URLSessionDataTask

    Parameters

    playlistID

    the given playlist ID.
    territory

    the given territory
    callback

    the callback block

    Return Value

    an NSURLSessionDataTask object that allow you to cancel the task.

    Show on GitHub

  • Fetches information and song tracks of a given playlist.

    See https://docs-en.kkbox.codes/v1.1/reference#shared-playlists_playlist_id_tracks.

    Declaration

    Objective-C

    - (nonnull NSURLSessionDataTask *)
    fetchTracksInPlaylistWithPlaylistID:(nonnull NSString *)playlistID
                              territory:(KKTerritoryCode)territory
                               callback:(nonnull void (^)(
                                            NSArray<KKTrackInfo *> *_Nullable,
                                            KKPagingInfo *_Nullable,
                                            KKSummary *_Nullable,
                                            NSError *_Nullable))callback;

    Swift

    func fetchTracksInPlaylist(withPlaylistID playlistID: String, territory: KKTerritoryCode, callback: @escaping ([KKTrackInfo]?, KKPagingInfo?, KKSummary?, Error?) -> Void) -> URLSessionDataTask

    Parameters

    playlistID

    the given playlist ID.
    territory

    the given territory
    callback

    the callback block

    Return Value

    an NSURLSessionDataTask object that allow you to cancel the task.

    Show on GitHub

  • Fetches information and song tracks of a given playlist.

    See https://docs-en.kkbox.codes/v1.1/reference#shared-playlists_playlist_id_tracks.

    Declaration

    Objective-C

    - (nonnull NSURLSessionDataTask *)
    fetchTracksInPlaylistWithPlaylistID:(nonnull NSString *)playlistID
                              territory:(KKTerritoryCode)territory
                                 offset:(NSInteger)offset
                                  limit:(NSInteger)limit
                               callback:(nonnull void (^)(
                                            NSArray<KKTrackInfo *> *_Nullable,
                                            KKPagingInfo *_Nullable,
                                            KKSummary *_Nullable,
                                            NSError *_Nullable))callback;

    Swift

    func fetchTracksInPlaylist(withPlaylistID playlistID: String, territory: KKTerritoryCode, offset: Int, limit: Int, callback: @escaping ([KKTrackInfo]?, KKPagingInfo?, KKSummary?, Error?) -> Void) -> URLSessionDataTask

    Parameters

    playlistID

    the given playlist ID.
    territory

    the given territory
    offset

    the offset
    limit

    the limit of response
    callback

    the callback block

    Return Value

    an NSURLSessionDataTask object that allow you to cancel the task.

    Show on GitHub

Featured Playlists

  • Fetch featured playlists.

    See https://docs-en.kkbox.codes/v1.1/reference#featured-playlists. See also fetchPlaylistWithPlaylistID:territory:callback:.

    Declaration

    Objective-C

    - (nonnull NSURLSessionDataTask *)
    fetchFeaturedPlaylistsForTerritory:(KKTerritoryCode)territory
                              callback:(nonnull void (^)(
                                           NSArray<KKPlaylistInfo *> *_Nullable,
                                           KKPagingInfo *_Nullable,
                                           KKSummary *_Nullable,
                                           NSError *_Nullable))callback;

    Swift

    func fetchFeaturedPlaylists(forTerritory territory: KKTerritoryCode, callback: @escaping ([KKPlaylistInfo]?, KKPagingInfo?, KKSummary?, Error?) -> Void) -> URLSessionDataTask

    Parameters

    territory

    the given territory
    callback

    the callback block

    Return Value

    an NSURLSessionDataTask object that allow you to cancel the task.

    Show on GitHub

  • Fetch featured playlists.

    See https://docs-en.kkbox.codes/v1.1/reference#featured-playlists. See also fetchPlaylistWithPlaylistID:territory:callback:.

    Declaration

    Objective-C

    - (nonnull NSURLSessionDataTask *)
    fetchFeaturedPlaylistsForTerritory:(KKTerritoryCode)territory
                                offset:(NSInteger)offset
                                 limit:(NSInteger)limit
                              callback:(nonnull void (^)(
                                           NSArray<KKPlaylistInfo *> *_Nullable,
                                           KKPagingInfo *_Nullable,
                                           KKSummary *_Nullable,
                                           NSError *_Nullable))callback;

    Swift

    func fetchFeaturedPlaylists(forTerritory territory: KKTerritoryCode, offset: Int, limit: Int, callback: @escaping ([KKPlaylistInfo]?, KKPagingInfo?, KKSummary?, Error?) -> Void) -> URLSessionDataTask

    Parameters

    territory

    the given territory
    offset

    the offset
    limit

    the limit of response
    callback

    the callback block

    Return Value

    an NSURLSessionDataTask object that allow you to cancel the task.

    Show on GitHub

New-Hits Playlists

  • Fetch new hits playlists.

    See https://docs-en.kkbox.codes/v1.1/reference#new-hits-playlists. See also fetchPlaylistWithPlaylistID:territory:callback:.

    Declaration

    Objective-C

    - (nonnull NSURLSessionDataTask *)
    fetchNewHitsPlaylistsForTerritory:(KKTerritoryCode)territory
                             callback:(nonnull void (^)(
                                          NSArray<KKPlaylistInfo *> *_Nullable,
                                          KKPagingInfo *_Nullable,
                                          KKSummary *_Nullable,
                                          NSError *_Nullable))callback;

    Swift

    func fetchNewHitsPlaylists(forTerritory territory: KKTerritoryCode, callback: @escaping ([KKPlaylistInfo]?, KKPagingInfo?, KKSummary?, Error?) -> Void) -> URLSessionDataTask

    Parameters

    territory

    the given territory
    callback

    the callback block

    Return Value

    an NSURLSessionDataTask object that allow you to cancel the task.

    Show on GitHub

  • Fetch new hits playlists.

    See https://docs-en.kkbox.codes/v1.1/reference#new-hits-playlists. See also fetchPlaylistWithPlaylistID:territory:callback:.

    Declaration

    Objective-C

    - (nonnull NSURLSessionDataTask *)
    fetchNewHitsPlaylistsForTerritory:(KKTerritoryCode)territory
                               offset:(NSInteger)offset
                                limit:(NSInteger)limit
                             callback:(nonnull void (^)(
                                          NSArray<KKPlaylistInfo *> *_Nullable,
                                          KKPagingInfo *_Nullable,
                                          KKSummary *_Nullable,
                                          NSError *_Nullable))callback;

    Swift

    func fetchNewHitsPlaylists(forTerritory territory: KKTerritoryCode, offset: Int, limit: Int, callback: @escaping ([KKPlaylistInfo]?, KKPagingInfo?, KKSummary?, Error?) -> Void) -> URLSessionDataTask

    Parameters

    territory

    the given territory
    offset

    the offset
    limit

    the limit of response
    callback

    the callback block

    Return Value

    an NSURLSessionDataTask object that allow you to cancel the task.

    Show on GitHub

Featured Playlists Categories

Mood Station

  • Fetch mood station categories.

    See https://docs-en.kkbox.codes/v1.1/reference#mood-stations.

    Declaration

    Objective-C

    - (nonnull NSURLSessionDataTask *)
    fetchMoodStationsForTerritory:(KKTerritoryCode)territory
                         callback:(nonnull void (^)(
                                      NSArray<KKRadioStation *> *_Nullable,
                                      KKPagingInfo *_Nullable,
                                      KKSummary *_Nullable,
                                      NSError *_Nullable))callback;

    Swift

    func fetchMoodStations(forTerritory territory: KKTerritoryCode, callback: @escaping ([KKRadioStation]?, KKPagingInfo?, KKSummary?, Error?) -> Void) -> URLSessionDataTask

    Parameters

    territory

    the given territory
    callback

    the callback block

    Return Value

    an NSURLSessionDataTask object that allow you to cancel the task.

    Show on GitHub

  • Fetch mood stations under a specific radio category.

    See https://docs-en.kkbox.codes/v1.1/reference#mood-stations_station_id.

    Declaration

    Objective-C

    - (nonnull NSURLSessionDataTask *)
    fetchMoodStationWithStationID:(nonnull NSString *)stationID
                        territory:(KKTerritoryCode)territory
                         callback:(nonnull void (^)(
                                      KKRadioStation *_Nullable,
                                      NSArray<KKTrackInfo *> *_Nullable,
                                      KKPagingInfo *_Nullable,
                                      KKSummary *_Nullable,
                                      NSError *_Nullable))callback;

    Swift

    func fetchMoodStation(withStationID stationID: String, territory: KKTerritoryCode, callback: @escaping (KKRadioStation?, [KKTrackInfo]?, KKPagingInfo?, KKSummary?, Error?) -> Void) -> URLSessionDataTask

    Parameters

    stationID

    the station ID. You can obtain IDs from the previous method.
    territory

    the given territory
    callback

    the callback block

    Return Value

    an NSURLSessionDataTask object that allow you to cancel the task.

    Show on GitHub

  • Fetch mood stations under a specific radio category.

    See https://docs-en.kkbox.codes/v1.1/reference#mood-stations_station_id.

    Declaration

    Objective-C

    - (nonnull NSURLSessionDataTask *)
    fetchMoodStationWithStationID:(nonnull NSString *)stationID
                        territory:(KKTerritoryCode)territory
                           offset:(NSInteger)offset
                            limit:(NSInteger)limit
                         callback:(nonnull void (^)(
                                      KKRadioStation *_Nullable,
                                      NSArray<KKTrackInfo *> *_Nullable,
                                      KKPagingInfo *_Nullable,
                                      KKSummary *_Nullable,
                                      NSError *_Nullable))callback;

    Swift

    func fetchMoodStation(withStationID stationID: String, territory: KKTerritoryCode, offset: Int, limit: Int, callback: @escaping (KKRadioStation?, [KKTrackInfo]?, KKPagingInfo?, KKSummary?, Error?) -> Void) -> URLSessionDataTask

    Parameters

    stationID

    the station ID. You can obtain IDs from the previous method.
    territory

    the given territory
    offset

    the offset
    limit

    the limit of response
    callback

    the callback block

    Return Value

    an NSURLSessionDataTask object that allow you to cancel the task.

    Show on GitHub

Genre Station

  • Fetch the list of genre radio station categories.

    See https://docs-en.kkbox.codes/v1.1/reference#genre-stations.

    Declaration

    Objective-C

    - (nonnull NSURLSessionDataTask *)
    fetchGenreStationsForTerritory:(KKTerritoryCode)territory
                          callback:(nonnull void (^)(
                                       NSArray<KKRadioStation *> *_Nullable,
                                       KKPagingInfo *_Nullable,
                                       KKSummary *_Nullable,
                                       NSError *_Nullable))callback;

    Swift

    func fetchGenreStations(forTerritory territory: KKTerritoryCode, callback: @escaping ([KKRadioStation]?, KKPagingInfo?, KKSummary?, Error?) -> Void) -> URLSessionDataTask

    Parameters

    territory

    the given territory
    callback

    the callback block

    Return Value

    an NSURLSessionDataTask object that allow you to cancel the task.

    Show on GitHub

  • Fetch genre-based radio stations under a specific genre category.

    See https://docs-en.kkbox.codes/v1.1/reference#genre-stations_station_id.

    Declaration

    Objective-C

    - (nonnull NSURLSessionDataTask *)
    fetchGenreStationWithStationID:(nonnull NSString *)stationID
                         territory:(KKTerritoryCode)territory
                          callback:(nonnull void (^)(
                                       KKRadioStation *_Nullable,
                                       NSArray<KKTrackInfo *> *_Nullable,
                                       KKPagingInfo *_Nullable,
                                       KKSummary *_Nullable,
                                       NSError *_Nullable))callback;

    Swift

    func fetchGenreStation(withStationID stationID: String, territory: KKTerritoryCode, callback: @escaping (KKRadioStation?, [KKTrackInfo]?, KKPagingInfo?, KKSummary?, Error?) -> Void) -> URLSessionDataTask

    Parameters

    stationID

    the station ID. You can obtain the list categories from the previous method.
    territory

    the given territory
    callback

    the callback block

    Return Value

    an NSURLSessionDataTask object that allow you to cancel the task.

    Show on GitHub

  • Fetch genre-based radio stations under a specific genre category.

    See https://docs-en.kkbox.codes/v1.1/reference#genre-stations_station_id.

    Declaration

    Objective-C

    - (nonnull NSURLSessionDataTask *)
    fetchGenreStationWithStationID:(nonnull NSString *)stationID
                         territory:(KKTerritoryCode)territory
                            offset:(NSInteger)offset
                             limit:(NSInteger)limit
                          callback:(nonnull void (^)(
                                       KKRadioStation *_Nullable,
                                       NSArray<KKTrackInfo *> *_Nullable,
                                       KKPagingInfo *_Nullable,
                                       KKSummary *_Nullable,
                                       NSError *_Nullable))callback;

    Swift

    func fetchGenreStation(withStationID stationID: String, territory: KKTerritoryCode, offset: Int, limit: Int, callback: @escaping (KKRadioStation?, [KKTrackInfo]?, KKPagingInfo?, KKSummary?, Error?) -> Void) -> URLSessionDataTask

    Parameters

    stationID

    the station ID. You can obtain the list categories from the previous method.
    territory

    the given territory
    offset

    the offset
    limit

    the limit of response
    callback

    the callback block

    Return Value

    an NSURLSessionDataTask object that allow you to cancel the task.

    Show on GitHub

Search

  • Search within KKBOX’s archive.

    See https://docs-en.kkbox.codes/v1.1/reference#search_1.

    Declaration

    Objective-C

    - (nonnull NSURLSessionDataTask *)
    searchWithKeyword:(nonnull NSString *)keyword
          searchTypes:(KKSearchType)searchTypes
            territory:(KKTerritoryCode)territory
             callback:(nonnull void (^)(KKSearchResults *_Nullable,
                                        NSError *_Nullable))callback;

    Swift

    func search(withKeyword keyword: String, searchTypes: KKSearchType, territory: KKTerritoryCode, callback: @escaping (KKSearchResults?, Error?) -> Void) -> URLSessionDataTask

    Parameters

    keyword

    the keyword
    searchTypes

    search for song tracks, albums, artists or playlists.
    territory

    the given territory
    callback

    the callback block

    Return Value

    an NSURLSessionDataTask object that allow you to cancel the task.

    Show on GitHub

  • Search within KKBOX’s archive.

    See https://docs-en.kkbox.codes/v1.1/reference#search.

    Declaration

    Objective-C

    - (nonnull NSURLSessionDataTask *)
    searchWithKeyword:(nonnull NSString *)keyword
          searchTypes:(KKSearchType)searchTypes
            territory:(KKTerritoryCode)territory
               offset:(NSInteger)offset
                limit:(NSInteger)limit
             callback:(nonnull void (^)(KKSearchResults *_Nullable,
                                        NSError *_Nullable))callback;

    Swift

    func search(withKeyword keyword: String, searchTypes: KKSearchType, territory: KKTerritoryCode, offset: Int, limit: Int, callback: @escaping (KKSearchResults?, Error?) -> Void) -> URLSessionDataTask

    Parameters

    keyword

    the keyword
    searchTypes

    search for song tracks, albums, artists or playlists.
    territory

    the given territory
    offset

    the offset
    limit

    the limit of response
    callback

    the callback block

    Return Value

    an NSURLSessionDataTask object that allow you to cancel the task.

    Show on GitHub

New Releases

  • Fetch the categories of new released albums in a specific territory.

    See https://docs-en.kkbox.codes/v1.1/reference#new-release-categories.

    Declaration

    Objective-C

    - (nonnull NSURLSessionDataTask *)
    fetchNewReleaseAlbumCategoriesForTerritory:(KKTerritoryCode)territory
                                      callback:
                                          (nonnull void (^)(
                                              NSArray<KKNewReleaseAlbumsCategory
                                                          *> *_Nullable,
                                              KKPagingInfo *_Nullable,
                                              KKSummary *_Nullable,
                                              NSError *_Nullable))callback;

    Swift

    func fetchNewReleaseAlbumCategories(forTerritory territory: KKTerritoryCode, callback: @escaping ([KKNewReleaseAlbumsCategory]?, KKPagingInfo?, KKSummary?, Error?) -> Void) -> URLSessionDataTask

    Parameters

    territory

    the given territory. KKBOX may provide different new released albums in different territories.
    callback

    the callback block

    Return Value

    an NSURLSessionDataTask object that allow you to cancel the task.

    Show on GitHub

  • Fetch the categories of new released albums in a specific territory.

    See https://docs-en.kkbox.codes/v1.1/reference#new-release-categories.

    Declaration

    Objective-C

    - (nonnull NSURLSessionDataTask *)
    fetchNewReleaseAlbumCategoriesForTerritory:(KKTerritoryCode)territory
                                        offset:(NSInteger)offset
                                         limit:(NSInteger)limit
                                      callback:
                                          (nonnull void (^)(
                                              NSArray<KKNewReleaseAlbumsCategory
                                                          *> *_Nullable,
                                              KKPagingInfo *_Nullable,
                                              KKSummary *_Nullable,
                                              NSError *_Nullable))callback;

    Swift

    func fetchNewReleaseAlbumCategories(forTerritory territory: KKTerritoryCode, offset: Int, limit: Int, callback: @escaping ([KKNewReleaseAlbumsCategory]?, KKPagingInfo?, KKSummary?, Error?) -> Void) -> URLSessionDataTask

    Parameters

    territory

    the given territory. KKBOX may provide different new released albums in different territories.
    offset

    the offset
    limit

    the limit of response
    callback

    the callback block

    Return Value

    an NSURLSessionDataTask object that allow you to cancel the task.

    Show on GitHub

  • Fetch new released albums in a specific category and territory.

    See https://docs-en.kkbox.codes/v1.1/reference#new-release-categories_category_id.

    Declaration

    Objective-C

    - (nonnull NSURLSessionDataTask *)
    fetchNewReleaseAlbumsUnderCategory:(nonnull NSString *)categoryID
                             territory:(KKTerritoryCode)territory
                              callback:
                                  (nonnull void (^)(
                                      KKNewReleaseAlbumsCategory *_Nullable,
                                      NSArray<KKAlbumInfo *> *_Nullable,
                                      KKPagingInfo *_Nullable,
                                      KKSummary *_Nullable,
                                      NSError *_Nullable))callback;

    Swift

    func fetchNewReleaseAlbumsUnderCategory(_ categoryID: String, territory: KKTerritoryCode, callback: @escaping (KKNewReleaseAlbumsCategory?, [KKAlbumInfo]?, KKPagingInfo?, KKSummary?, Error?) -> Void) -> URLSessionDataTask

    Parameters

    categoryID

    the ID of the category.
    territory

    the given territory. KKBOX may provide different new released albums in different territories.
    callback

    the callback block

    Return Value

    an NSURLSessionDataTask object that allow you to cancel the task.

    Show on GitHub

  • Fetch new released albums in a specific category and territory.

    See https://docs-en.kkbox.codes/v1.1/reference#new-release-categories_category_id.

    Declaration

    Objective-C

    - (nonnull NSURLSessionDataTask *)
    fetchNewReleaseAlbumsUnderCategory:(nonnull NSString *)categoryID
                             territory:(KKTerritoryCode)territory
                                offset:(NSInteger)offset
                                 limit:(NSInteger)limit
                              callback:
                                  (nonnull void (^)(
                                      KKNewReleaseAlbumsCategory *_Nullable,
                                      NSArray<KKAlbumInfo *> *_Nullable,
                                      KKPagingInfo *_Nullable,
                                      KKSummary *_Nullable,
                                      NSError *_Nullable))callback;

    Swift

    func fetchNewReleaseAlbumsUnderCategory(_ categoryID: String, territory: KKTerritoryCode, offset: Int, limit: Int, callback: @escaping (KKNewReleaseAlbumsCategory?, [KKAlbumInfo]?, KKPagingInfo?, KKSummary?, Error?) -> Void) -> URLSessionDataTask

    Parameters

    categoryID

    the ID of the category.
    territory

    the given territory. KKBOX may provide different new released albums in different territories.
    offset

    the offset
    limit

    the limit of response
    callback

    the callback block

    Return Value

    an NSURLSessionDataTask object that allow you to cancel the task.

    Show on GitHub

Charts

  • Fetch the categories of charts in a specific territory.

    See https://docs-en.kkbox.codes/v1.1/reference#charts. See also fetchPlaylistWithPlaylistID:territory:callback:.

    Declaration

    Objective-C

    - (nonnull NSURLSessionDataTask *)
    fetchChartsForTerritory:(KKTerritoryCode)territory
                   callback:
                       (nonnull void (^)(NSArray<KKPlaylistInfo *> *_Nullable,
                                         KKPagingInfo *_Nullable,
                                         KKSummary *_Nullable,
                                         NSError *_Nullable))callback;

    Swift

    func fetchCharts(forTerritory territory: KKTerritoryCode, callback: @escaping ([KKPlaylistInfo]?, KKPagingInfo?, KKSummary?, Error?) -> Void) -> URLSessionDataTask

    Parameters

    territory

    the given territory. KKBOX may provide different charts in different territories.
    callback

    the callback block

    Return Value

    an NSURLSessionDataTask object that allow you to cancel the task.

    Show on GitHub

  • Fetch the categories of charts in a specific territory.

    See https://docs-en.kkbox.codes/v1.1/reference#charts. See also fetchPlaylistWithPlaylistID:territory:callback:.

    Declaration

    Objective-C

    - (nonnull NSURLSessionDataTask *)
    fetchChartsForTerritory:(KKTerritoryCode)territory
                     offset:(NSInteger)offset
                      limit:(NSInteger)limit
                   callback:
                       (nonnull void (^)(NSArray<KKPlaylistInfo *> *_Nullable,
                                         KKPagingInfo *_Nullable,
                                         KKSummary *_Nullable,
                                         NSError *_Nullable))callback;

    Swift

    func fetchCharts(forTerritory territory: KKTerritoryCode, offset: Int, limit: Int, callback: @escaping ([KKPlaylistInfo]?, KKPagingInfo?, KKSummary?, Error?) -> Void) -> URLSessionDataTask

    Parameters

    territory

    the given territory. KKBOX may provide different charts in different territories.
    offset

    the offset
    limit

    the limit of response
    callback

    the callback block

    Return Value

    an NSURLSessionDataTask object that allow you to cancel the task.

    Show on GitHub