Using the SoundCloud API with the JavaScript SDK
SoundCloud has made available an API which allows developers to get almost any data they want. But its usage can be confusing, especially for beginners, because as of now the SoundCloud API documentation and the examples use different versions of the SDK (Software Development Kit).
What is the difference between the API and the SDK? Basically, the API is a collection of URLs that provide access to data from the SoundCloud servers, and the SDK is a pre-written library (or client) for querying the API. To learn more see this discussion.
In this tutorial, we will learn how to access the SoundCloud API and how to simplify the process using the SDK. We will walk though setting up the SDK and then write the JavaScript to get data, play audio and more from SoundCloud.
Getting Started
Knowing the concepts and workings of HTTP and APIs will be helpful. If you want to learn more about APIs, I recommend this short course: An Introduction to APIs. A little knowledge of asynchronous JavaScript, promises and callbacks will also help. jQuery is used in our code examples, so knowing the basics won’t hurt.
To start querying the SoundCloud API using JavaScript, we need to download the JavaScript SDK provided by SoundCloud. As mentioned earlier, there are two different versions of the SDK available.
Which Version of the SDK to Use?
The major difference between them is how they return data when an asynchronous request is made to the API. The latest version returns a Promise, while the other requires a callback function as a parameter.
One problem I noticed, is that with the version of SDK used by the documentation, there seems to be an issue with user-login functionality, as the pop-up window doesn’t close automatically.
So, for simplicity’s sake, and because it is more stable, we will use the old version in the examples throughout this tutorial. This version will require callback functions for asynchronous requests.
Using the SoundCloud API
Setup a Basic HTML Document
We will create a basic HTML page which will serve as our homepage. We will also include the SDK here, so we can make use of its functionality.
<!DOCTYPE html>
<html>
<head>
<title>Include SDK - Using SoundCloud API</title>
<script src="//connect.soundcloud.com/sdk.js"></script>
</head>
<body></body>
</html>
Notice that we have included the SDK in our page directly from SoundCloud’s servers. You can also download the SDK and reference to it like:
<script src="sdk.js"></script>
To test if the SDK gets loaded in your webpage correctly:
- Open up the page in a browser (Chrome recommended).
- Open up Developer Console in the browser (Ctrl + Shift + J, in Chrome).
- In the Console, type
SCand press enter.SCis a Javascript Object created by the SDK which we just included.
If an undefined error shows up then it is not loading correctly. Try refreshing and make sure the path to the SDK file (sdk.js) is correct.
Register a SoundCloud App
To register a SoundCloud app, all you need is a SoundCloud account. If you don’t have one already, go ahead and create one. By registering an app, SoundCloud servers will be able to verify our request, so no one else can make a request on our behalf.
Note: We can skip this step, if we are not going to use the user-login feature in our website. It will be explained in the next section.
Open the SoundCloud apps page. Here any apps we have already created will be listed. Make sure you are logged in to your SoundCloud account. Note: You do not need to make a separate account for this purpose. You can use the same account which you use for personal purposes.
Click on the Register a new application button.
Give it a name and accept SoundCloud’s Developer Policies by checking the checkbox.
Click on the big Register button, to complete the app registration.
After we have successfully registered, we will be redirected to the settings page of our newly created app. There we will find our app’s Client ID, which will be used to authorize our requests. We can leave the website and callback fields for now. We’ll get to that later.
Initialize the Client
By “initializing the client”, we mean to make the client ready to exchange data between itself and SoundCloud API. We can do it in our basic HTML document, which we created earlier, or in an external .js file.
The JavaScript syntax to do so is:
SC.initialize({
client_id: "CLIENT_ID",
redirect_uri: "CALLBACK_URL"
});
Let’s break it down:
- The
CLIENT_IDis provided to us when we register our app. CALLBACK_URLis the URL tocallback.html, an HTML file which gets called after the user has logged in. We will create it soon.
Now, after initialization, we are ready to query the SoundCloud API. Let’s take a look at some examples of what we can do already.
Examples
If we open up browser console and type SC., a list of methods associated with the SC object will appear. SC.get(uri, callback) is one of them, which is used for making GET requests to the API.
Getting a List of Tracks
To get a list of random tracks, we can use SC.get() like this:
SC.get("/tracks", function(response) {
for (var i = 0; i < response.length; i++) {
$("ul").append("<li>" + response[i].title + "</li>");
}
});
Continue reading %Using the SoundCloud API with the JavaScript SDK%
LEAVE A REPLY
You must be logged in to post a comment.