The KKBOX English Developer Hub

Welcome to the KKBOX English developer hub. You'll find comprehensive guides and documentation to help you start working with KKBOX English as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Beginner's Guide for Python Developers

Helps you get familiar with KKBOX Open API with Python.


KKBOX Open API gives you a way to seek through the most extensive music database in Asia. This guide helps you get familiar with KKBOX Open API with the programming language Python. In this guide, you will learn how to:

  1. Create application credentials
  2. Learn how to authorize yourself to KKBOX Open API.
  3. Know where to find the reference for KKBOX Open API.
  4. Write an example code using Python and KKBOX Python SDK: Search for playlists using keyword 'workout' and fetch all the tracks from the first playlist of the searching results.
  5. Integrate with KKBOX HTML Widget.

We will be using Python and the KKBOX Python SDK for accessing the Web API, and you can download all the source code in this guide from our GitHub.

Create application credentials

To access KKBOX Open API, you have to register yourself to the KKBOX service so we can recognize who made the request. Go to My Apps page on the developer site, and log in with either your KKBOX account or a Facebook account. After logging in, you should see the following page:

By far you should not have any application credentials created. Click Create new app button, and you will be guided to the creation page. Choose a name and the description for your application credentials. Let's choose 'Getting Started' for now.

Click Submit, and now you should see a page like this:

Voilà, an application credentials has been created! It contains two important values:

  • ID: The unique identifier of your application.
  • Secret: The secret key for authenticating the application to the Web API. Do not reveal the secret key to others.

Once you have the ID and Secret, you are now ready to access the Web API. In the next chapter, you will learn how to authorize yourself to the server and request for an access token.


Setting up Python environment

We will have to write some Python starting from this chapter, so let's get the environment prepared.

First, install the KKBOX Python SDK through pip:

$ pip install kkbox-developer-sdk

That's it, now you are ready ;)


KKBOX Open API requires authorization for all its endpoints. The authorization flow is based on OAuth 2.0. Currently, only client credentials grant flow is supported. In this flow, an application is authorized by the server if the given application ID and Secret are valid. Here's the process of client credentials grant flow:

  1. The application request for an access token from KKBOX Authorization Server (See below) with its ID and a Secret.
  2. If the given ID and Secret are valid, the server will respond an access token and other information related to the token.
  3. The application uses the access token to request for resources from KKBOX Open API.
  4. When the token expired, the application needs to request another token from KKBOX Authorization Server, and use the new access token to request for resources from KKBOX Open API.

KKBOX Authorization Server: The server for authorizing an application or a user. For OAuth 2.0 authorization, the URL will be

Request for access token

Request for an access token using KKBOX Python SDK is fairly easy:

from kkbox_developer_sdk.auth_flow import KKBOXOAuth
auth = KKBOXOAuth(CLIENT_ID, CLIENT_SECRET)  # Replace CLIENT_ID and CLIENT_SECRET with your ID and Secret
token = auth.fetch_access_token_by_client_credentials()

After running the code above, you should now see something like:


This is the access token, which is a base64 encoded string. You have to provide this token whenever you access the KKBOX Open API.

Access KKBOX Open API

Note: Before proceeding, Please make sure you have followed chapter Authorization for setting up the Python environment and acquired the access token.

API References

With the access token acquired from the preceding chapter, you are now able to access the KKBOX Open API. To see what KKBOX Open API is capable of, visit the Reference page on KKBOX Open API Document site.

Suppose you want to search something in KKBOX, you can click Search on the left panel, then all the endpoints related to Search will appear:

The endpoints related to Search is just /search. Click it, and now the center panel will show how to use the /search endpoint:

You can find all sorts of information in center panel:

  • HTTP Method
  • Full URL
  • Various programming language examples
  • Required query parameters and/or body parameters

On the right panel, a response to the example request is shown.

In addition to all the references information, the Reference page also has a built-in API Console for trying out each API without writing any code.

Accessing KKBOX Open API with Python

Searching for playlists with keyword 'workout'

Here's an example of searching playlists with keyword 'workout' using KKBOX Python SDK:

from kkbox_developer_sdk.api import KKBOXAPI
kkboxapi = KKBOXAPI(token)
search_results ='workout', types=['playlist'], terr='TW')

If you try to dump search_results to the screen, you would see that it contains a huge amount of data. Don't be frightened, this is a pagination object. To access the searching results, you have to specify:

playlists = search_results['playlists']['data']

Still hard to read? Let's just fetch the first result and print it with pprint:

first = playlists[0]
from pprint import pprint
pprint(first, depth=2)

You should see something like this:

{'description': '最厲害的冠軍Pop流行動感舞曲,跑步、健身房重量訓練必備!!',
 'id': 'Otv4S0erPHGatlMkoJ',
 'images': [{...}, {...}, {...}],
 'owner': {'description': '這次我要播很多 華語 類別的歌曲,快來跟我一起聽音樂吧!',
           'id': 'D_YoomYcGauVGLHfua',
           'images': [...],
           'name': '索尼大台柱',
           'url': ''},
 'title': '跟上節奏慢跑Workout (12/30更新)',
 'updated_at': '2017-12-30T12:03:33+00:00',
 'url': ''}

This is a playlist object. As you can see, it has several properties, including id, title, and description. In the next section, we are going to use the id of the playlist to fetch all the tracks from the playlist.

Fetching all the tracks from the first searching result

With the playlist ID, we could request for tracks in the playlist:

tracks_paging = kkboxapi.shared_playlist_fetcher.fetch_tracks_of_shared_playlists('Otv4S0erPHGatlMkoJ')
tracks = tracks_paging['data']
pprint(tracks, depth=2)

And the results are:

[{'album': {...},
  'available_territories': [...],
  'duration': 216920,
  'explicitness': False,
  'id': '9XTEZyky3wYrA8a0dU',
  'name': 'Havana',
  'track_number': 1,
  'url': ''},
 {'album': {...},
  'available_territories': [...],
  'duration': 203023,
  'explicitness': False,
  'id': 'OraVq5QVf78HW_IAHz',
  'name': 'More Than You Know',
  'track_number': 1,
  'url': ''},
 {'album': {...},
  'available_territories': [...],
  'duration': 199131,
  'explicitness': False,
  'id': 'GswD0aVEZ-QUZzhnUy',
  'name': 'All Falls Down',
  'track_number': 1,
  'url': ''},

Each of the objects in tracks list is a track object, which has properties like name, track_number, id, etc. This is one of the ways to search for a playlist and list all the tracks from the playlist.

Integrate with KKBOX HTML Widget

KKBOX HTML Widget is a snippet of HTML code which you can embed in your web page to show a playlist, album or track information, depends on the URL of the Widget. Besides, the widget has the capability of playing the trial version (30 seconds) of a song, so it is an excellent tool for you to integrate the content provided by KKBOX Open API with your web page.

In this chapter, we are going to show you how to create a widget that displays:

  1. The playlist we just searched
  2. A song in that playlist.

Playlist Widget

To display a playlist in a widget, you have to specify the ID of the playlist and set the type to playlist. Take the playlist ID we just searched (Otv4S0erPHGatlMkoJ) as an example, the URL for the widget should be:

You can click on the URL to see the how the widget renders a playlist. In addition to playlist ID and type, you can also modify several options on the widget like language or autoplay. See HTML Widgets for the options you can specify.

Song Widget

To display a song in a widget, you have to specify the ID of the song and set the type to 'song.' Take one song ID from the playlist we just searched (OraVq5QVf78HW_IAHz), the URL for the widget should be:

You can click on the URL to see how the widget displays a song. Notice that it might seem weird that the widget stretched all the way to the width of your browser window. That is because the widget is not meant to be rendered as a page, what we did here is just a demonstration. See here for how to use it as a widget.

Congratulations! You have finished the guide! If you have any further questions, you could post a question in Support, or write an email to [email protected], we are happy to answer all of your questions.

Updated 2 years ago

Beginner's Guide for Python Developers

Helps you get familiar with KKBOX Open API with Python.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.