Using the Songclip API

Welcome to this introduction on how to use the Songclip API!

If you’re new here, Songclip provides an API service for web and app developers to use licensed music in their work.

We’ve partnered with the major record labels to provide millions of popular clips, from current Billboard hits to golden oldies, you can integrate into your app, enhancing the user experience. If you’re interested in learning more please visit songclip.com and https://www.songclip.com/intro-form

Our full API documentation can be found at https://songclip.docs.apiary.io/. The purpose of this post however, is to provide a small sample application you can look through to get a better perspective on how you can integrate the API into your own apps.

Our sample application is a music player that lets you search the Songclip API for content and play it.

Screenshot of the application we’ll go through

It’s not going to win many aesthetic awards, but it will give an excellent overview of how to use the Songclip API in a real world setting. Let’s go over the app and how it uses the API.

Written with Flutter

You can find the app itself on github, here. It’s a modification of another repo that uses Flutter, a popular open source, cross-platform mobile development toolkit developed by Google. You’re welcome to install Flutter and run the app locally but it’s not 100% necessary in order to follow this guide.

The repo we’ve cloned from is for a library that lets you play, pause and fast-forward through music that is either local to the device or on the web — perfect for our purposes.

We’re going to use Visual Studio Code as our editor and build tool, which is available for MacOS, Windows and Ubuntu. (You can also use Android Studio to build and run the app, if that’s your preference.) You can find installation instructions for Flutter and how to integrate with VS Code here.

If you clone the repo and open it in either VS Code or Android Studio you’ll see the project uses the Dart programming language, as do all Flutter apps. If you’ve never used Dart before its syntax is very similar to Typescript and Javsascript and if you’ve used them or any modern OOP language you shouldn’t have much trouble following along.

The app has a number of support and ancillary folders in it, mainly due to the need to support iOS and Android architectures, but the important one for our purposes is the example\lib folder:

The section we’ll be working in

While main.dart and player_widget.dart provide the UI for the app, and you are more than welcome to look in there to see how it works, the file we’re most interested in, the one with the API calls, is api_calls.dart

Let’s look at it in detail, starting at the top:

It starts with a series of import statements, for http and other dart libraries, much like you see in any OOP language, Javascript and Typescript included.

After that we define an authorization header and key used for our API calls, along with a disclaimer. Let’s discuss that disclaimer briefly.

Keep your keys safe — meaning, off the device

This app’s purpose is to give a working demonstration on how to use the Songclip API. As such, it’s been kept focused on that goal. One of the ways we keep things simple is by hard-coding the authorization header and API key in the code itself. In practice this is a bad idea. The best approach is to keep that information in a server and use it as a proxy between the device and the Songclip API.

It’s true that iOS and Android (and Flutter) have keystore libraries you can use to store sensitive information in, but the safest approach is to store API keys on a server you control and not on a device.

With disclaimers out of the way, let’s take a look at our first API call. Again, this is in api_calls.dart :

We’re using Dart’s http library to make the request. Its syntax is the same as most other popular http libraries, such as Axios for Javascript.
In our case we’re providing our Authorization header along with one for our API key; this is something you’ll need to provide for all Songclip API calls.

This first call is a simple GET to our search API with ‘love’ as the search term. We also include a shuffle parameter that randomizes the order in which the clips are returned, and we limit our search to 20 clips.

We get an http response and retrieve the songclips object from it, convert that from json to a list of customClip objects, which we then return to our app for display.

Note the use of Future<List<Clip>> as the function return type. This is just Dart at work — Future is Dart’s equivalent to a Javascript promise, and it uses generics to say ‘return a Future that will resolve to list of Clip objects.’

This ‘promise-like’ familiarity extends to the calling code, which is identical to what you’d see in javascript or C# — var retval = await fetchClips()

Post requests

Now that we’ve seen what a search request looks like, let’s see how we would report events like play and share. This snippet also comes from api_calls.dart —

Again, we’re returning a Future, this time with an http response as the return type. Note that we again supply an authorization header and API key, same as before.

The big difference between our Search call and this one is the Play event uses a POST instead of GET, so we need to provide a body for the request.

The exact syntax varies from one library and language to another, but in general you’ll create a request body object and put your data in there. For the Songclip API we have three parameters we need for every reporting API call:

1. The sourcePlatform. This is to identify the device type that’s calling the event. In this case it’s an iOS device, and other options include Android and Web.
2. A sessionId. This identifies the flow through our system and helps track how Songclip is being used in your app — how many searches users are making vs the number of plays and shares, how long the app is open, etc. If an API call doesn’t provide a sessionId we’ll return one to you, which you can then use for the remainder of that session. So for instance, if you call the app open event without a sessionId parameter you’ll get one in the response, and you can use it for the remainder of the user session.
3. A uniqueId. This is to uniquely identify a user so that metrics can be tracked for future API improvements and to identify which clips and searches are the most popular. The uniqueId can be in any anonymized format you wish — GUIDs are popular — but should not contain any identifiable information such as email addresses or SSNs.
   The uniqueId should remain fixed between app launches for a given device.

Once you’ve established the request body you can JSON encode it, as we’ve done above, and then post your request.
If the request is successful you’ll see it in the status message, along with the uniqueId and sessionId you sent with it:

If there are any errors the response object will let you know in a validation errors section:

Let’s do one more POST example, this time for a Share event — this event you would call whenever someone shares a clip on Instagram, for example:

This is nearly identical to the Play event; it uses the same request body (encoded as JSON), with the only difference being the actual endpoint (events/share vs events/play)

And with that, you should be able to get started. Our other API calls, for App Open and Add and Favorite and Unfavorite, use a similar approach with the request body. If you remember to include the sourcePlatform, sessionId and uniqueId values in your requests, the API should respond to you with no issues and you can focus on how best to provide music through your application.