Content Services

Audiogum supports search, browse, authentication and playback across a broad range of content services as well as our own catalogue of artists.

Configuration

As music service functionality and availability varies, we offer a configuration API that returns details about which services are available as well as their capabilites.

APIPurpose
GET /v1/configGets various country-specific configuration such as which music services are supported.

Example service config

GET /v1/config

{
  "services": [ // services for this country
    {
      "id": "spotify",
      "name": "Spotify",
      "capabilities": [
        "search",
        "signin",
        "userplaylists",
        "listtracks"
      ],
      "searchtypes": [
        "playlist"
      ],
      "playback": {
        "account": "signin",
        "subscription": [
          "premium"
        ],
        "requires": "sdk"
      }
    }],
  "countrycode": "gb"
}

Capabilities

Services are marked as having certain "capabilities" that indicate which APIs can be used with them:

CapabilityDescription
browseService supports browsing content through nested lists. The GET /v1/browse/{service} API allows you to get the top-level lists and drill down into each list, until there are content items that may be played.
radiobrowseAs with browse, the service has browsable content through the GET /v1/browse/{service} API, but the content is either traditional radio or radio-style playlists. Services that support radiobrowse will also be marked as supporting browse, but this gives a finer level of detail if required by your UI.
remoteplaybackService supports remotely starting playback on a device. A list of devices available to the user can be obtained through GET /v1/user/{service}/devices and playback can be started through PUT /v1/user/{service}/devices/{deviceid}/player. The main example of this capability is Spotify, where Spotify Connect speakers can be listed and used to start playback of content.
searchService supports searching for content. The Audiogum configuration specifies the types of content searchable for each service and allows searching for specified types. The GET /v1/content API supports searching across multiple services simultaneously and returns content in a consistent format.
signinService requires a user account for playback of content and sign-in to the service should be offered in application settings. Once sign in is achieved, the user’s account on the service is “linked” to the user’s Audiogum account. Signin is an OAuth2 flow that is started by calling GET /v1/user/{service}/authorize in an embedded web browser or using an OAuth2 library and POST /v1/user/{service}/token to retrieve an access_token - see authentication below.
signinbrowseService requires a user account for browsing. The user cannot browse this service until their account on the service is "linked" to their Audiogum account (see signin capability).
sdksigninService requires a user account for playback of content and sign-in to the service should be offered in application settings. Once sign in is achieved, the user’s account on the service is “linked” to the user’s Audiogum account. Signin is achieved through a client SDK. POST /v1/user/{service}/token is used to store the access_token.
userplaylistsService supports listing the playlists belonging to or followed by the user on the service.
listtracksService supports listing playlist or album tracks
saveplaylistService supports creation of playlists through the POST /v1/user/{service}/playables/{id} api
localsaveplaylistService supports app SDK creation of playlists
dynamicplaylistService supports creation of Audiogum dynamic playlists

You can see the capabilities of each service on our availability page.

Playback

The playback part of the service configuration describes what is needed to play content:

RequirementDescription
accountIf signin is present, the user is required to sign in with a music service account - the method of signin is detailed in the service capabilities.
subscriptionIf present, means that a subscription is required - an array of subscription levels is given in the configuration and one of those should match the subscription attribute returned by the user details API.
requiresThe client playback requirements - will be one of http, https (HTTP-based progressive download supported), video when the content requires visual output or sdk (an SDK from the music service is required). For services offering HTTP(S) streaming, playables data will include the stream URL.
timelimitedThe content of an HTTP(S) stream is time limited - this configuration value is the time in seconds that a URL is valid for.
launcherService requires playback through their app. In this case, Audiogum still offers the ability to search and browse content, but the service's app must be used to play content. The value of launcher in the configuration gives the field to use to deep link into the service's app. For example, with Spotify, the ref field is used. For dynamic personalised playlists in the case of launcher services, the API allows an Audiogum generated playlist to be created and stored on the service for playback as a playlist.
platformIf present, indicates that playback is restricted only to the named platforms. For example, Apple Music is only available with an SDK on iOS.

You can see the requirement of each service on our availability page.

Search and Browse

The Search APIs allow your users to find relevant content quickly and also drill down into details to explore further.

The Browse API lets your users explore content from various music services. It returns a list of items of type category which can be explored with the ultimate goal of drilling down to items that aren't a category that can be played such as internetradio, audiobook or playlist. To explore a category, pass it's ref to this API in the parent parameter. Some services will return nested items within the category meaning no callback is required to explore further.

APIPurpose
GET /v1/browse/{service}Browse playlists and internet radio stations from music services.
GET /v1/contentSearch across music services for content. Returns search results in various "buckets" - e.g. Playlists, Radio Stations, Artists.
GET /v1/content/{type}/{service}Drill down into detailed results for paging through a 'bucket'. The service configuration shows which types are supported with the searchtypes attribute.
GET /v1/content/{type}Drill down into detailed results across services for paging through a 'bucket'.

Authentication

Where a music service offers authentication, Audiogum simplifies your integration with a consistent approach to signing in and user management. Typically, services allow sign-in through an OAuth2 flow where the user can securely sign in and grant permission without giving up their username or password.

Once a user is authenticated with a service, the service account is “linked” to the Audiogum user account and the access token is maintained by Audiogum service. This allows subsequent searching and browsing of the music service content via Audiogum API on behalf of the user without further authentication by the user.

Linked services also allow devices to request content from a service via the Audiogum Playables API without the device needing the user’s service credentials.

APIPurpose
GET /v1/user/linkedservicesGets details about all of the user's associated service accounts.
GET /v1/user/{service}/authorizeGet a URI to pass to a web browser to start a sign-in flow. Audiogum constructs the URI including requesting appropriate permissions.
POST /v1/user/{service}/tokenThis associates music service access details by taking the authorization_code from the end of the above sign-in flow.
GET /v1/user/{service}Gets details about the user's associated account.
DELETE /v1/user/{service}/tokenRemoves access for a service.
GET /v1/{service}/logo.pngGet the logo for a music service.
GET /v1/{service}/playerlogo.pngGet a smaller logo for a music service suitable to display on a now-playing screen.

Client OAuth2 Libraries

To help your app implement the OAuth2 signin for services, we have used and would recommend the following libraries:

PlatformLibrary
iOSOAuth2Client
AndroidAndroid OAuth Client Library
XamarinXamarin.Auth

Taste Profile import

Once the user has authenticated with the service, you can optionally add to their taste profile by importing taste preferences from the service. The POST /v1/user/taste/import/{service} API is used to automatically add to the user's taste profile when data is available from the service.

Service Availability

You can find the full list of content services Audiogum has integrated with on our availability page.