Content Aggregation

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

Configuration

As content 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 content services are supported.

Example service config

GET /v1/config

{
  "services": [ // services for this country
    {
      "id": "tidal",
      "name": "TIDAL",
      "capabilities": [
        "search",
        "saveplaylist",
        "signin",
        "browse",
        "dynamicplaylist",
        "userplaylists",
        "listitems"
      ],
      "upsell": {
      },
      "searchtypes": [
        "playlist",
        "album",
        "song"
      ],
      "drilldowntypes": [
        "albums",
        "singles",
        "songs"
      ],
      "playback": {
        "account": "signin",
        "subscription": [
          "premium"
        ],
        "requires": "http",
        "timelimited": 300
      }
    }],
  "countrycode": "gb",
  "loginproviders": [ ... ],
  "nativelogin": {"type": "email"},
  "tastetypes": ["album" "artist", ...]
}

Note that the config API also returns configuration used for login described in User Accounts.

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 with or without a user account. 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. See Search and Browse below for more information about this API.
dynamicplaylistService supports creation of Audiogum dynamic playlists.
listitemsService supports drilldown of items within a container - e.g. songs in a playlist or album - or episodes in a podcast. See drill down.
listtracksLegacy name for listitems, kept for compatibility.
localsaveplaylistService supports app SDK creation of playlists.
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. See Browse below for more information about this API.
radioshowService supports getting details of the current show for a specific radio station through the GET /v1/content/{type}/{service}/{ref} API that will include a currentshow object where available.
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. See Search below for more information about this API.
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 and searching content. 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.
saveplaylistService supports creation of playlists through the POST /v1/user/{service}/playables/{id} api

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

Subscription Capabilities

Some services require that the user has a certain kind of subscription in order to acquire a capability. For instance, the dynamicplaylist capability is available for Amazon Music customers, but only if they have an Amazon Music Unlimited subscription.

In the config response, where an additional capability is available but requires a certain subscription level will see this represented using the subscriptioncapabilities field:

GET /v1/config

{
  "services": [ // services for this country
    {
      "id": "amazon",
      "name": "Amazon Music"
      ...
      "subscriptioncapabilities": [
        {
          "capability": "dynamicplaylist",
          "subscription": [
            "unlimited"
          ]
        }
      ]
      ...
    }
  ]
}

If the user's subscription level matches any of the values given in the subscription field, then they will acquire the capability.

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 content service account - the method of signin is detailed in the service capabilities.
platformIf present, indicates that playback is restricted only to the named platforms. For example, Apple Music is only available with an SDK on iOS.
requiresThe client playback requirements - will be one of:
  • http, https (HTTP-based progressive download supported)
  • local - the content will have local URIs that have been sent for user catalogue matching by the manufacturer - e.g. smb://... or file://...
  • sdk - an SDK from the content service is required
  • video when the content requires visual output
For services offering HTTP(S) streaming, playables data will include the stream URL.
sendanalyticsIndicates that the service mandates sending of playback analytics.
sendcontinuationeventIndicates that the service mandates sending of a continue playback analytics event after the number of seconds specified have elapsed since the last event was sent. See Analytics Play Actions.
sendmediaeventsIndicates that the service mandates sending of mediabegin and mediaerror playback analytics events. See Analytics Play Actions.
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.
timelimitedThe content of an HTTP(S) stream is time limited - this configuration value is the time in seconds that a URL is valid for.

You can see the playback requirements for each service on our availability page.

Upsell (Free Trials)

Upon agreement with a content service, an optional service upsell configuration item may be present that includes text, an image uri and link to allow free trial offers to be enabled for your users when they don't have an existing account.

"upsell": {
  "type": "externalweblink",
  "imageuri": "https://.../upsell.png",
  "uri": "https://...",
  "text": "Get 1 month free"
}

Contractural, Media, Branding and Certification Requirements

You can find the details about what's needed for each service on our requirements page.


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

APIPurpose
GET /v1/contentSearch across content 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'.

Service configuration includes a searchtypes key that lists the types that are searchable - for example:

"searchtypes": [
  "playlist",
  "album",
  "song"
]


Browse

The Browse API lets your users explore content from various content 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 content services.

Where available, the Browse API provides hints to indicate the content contained within a category with the childtheme and childtype properties to allow display of iconography in your browse experience. Alternatively, some services support browse images which will be returned in an images object.

childtheme values

NameDescription
newThe child items are new releases
chartThe child items are chart or popular
featuredThe child items are featured editorial content
locationThe child items are location based
personalThe child items are selected or created by the user, such as user playlists
genreThe child items are genres or genre-themed
moodThe child items are moods or mood-themed
mixedThe child items are undeterminable or a mixture of the above

childtype values

NameDescription
albumThe child items are music albums
artistThe child items are music artists
authorThe child items are podcast or audiobook authors
audiobookThe child items are audiobooks
categoryThe child items are further categories
displayThe child items are textual display items
internetradioThe child items are internet radio stations
playlistThe child items are music playlists
podcastThe child items are podcasts
podcastepisodeThe child items are podcast episodes
radioplaylistThe child items are radio-style music playlists
singleThe child items are music singles
songThe child items are music songs
userThe child items are other users of the service

Paging

The Audiogum API cannot always determine the total number of items available after searching, browsing or getting child objects from a parent. Some content services do not offer any way to find the total number of items available, so the total field may be missing from the Audiogum response. For this reason, it's best that clients continue to ask for pages (by increasing the startindex by itemsperpage each time) until an empty page is received. Strategies such as dividing the total by itemsperpage to decide how many pages to retrieve may fail when total is missing.

Playback

Once an item has been found to play, follow our guide to playback.


Drill down

Services that support the listitems capability allow listing items from a container (e.g. songs for a playlist, episodes for podcast) with the GET /v1/content/{parenttype}/{service}/{ref}/{itemtype} API.

Service configuration includes a drilldowntypes key that lists the types that can be used as the itemtype - for example:

"drilldowntypes": [
  "albums",
  "singles",
  "songs"
]

Browse and Search results also includes a contains array that shows the types contained in an item - for example, an artist may contain albums and songs, a podcast may contain podcastepisodes.


Authentication

Where a content 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 content 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 links the content service access to the user's account 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}/tokenUnlinks the service account from the user's account.
GET /v1/{service}/logo.pngGet the logo for a content service.
GET /v1/{service}/playerlogo.pngGet a smaller logo for a content 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:

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. More details on the taste profile can be found on the Personalisation page.


Errors

The Audiogum platform standardises HTTP status codes and error formats across content services. The following table details the status codes and their meanings.

Status CodeMeaning
401Invalid or expired Audiogum access token - not related to content service
403No valid service token found for user. This error can occur when a token has expired or has been invalidated by concurrent usage. The user will need to re-authenticate.
404Content not found or service does not support this functionality.
409User has revoked access - some services allow revokation of 3rd party access.
410No items found to play on service - the item may have been removed or a dynamic playlist request may be too specific to allow enough items.
499The service returned a custom error message - see details below.
599The Content service API call failed or timed out

For the 499 status code, a service-specific response is included - currently only Amazon Music returns this.

Amazon Music

Amazon provides upsell prompts when a user does not have the rights to play:

{"error": {"terse": "Amazon Music Unlimited required",
           "brief": "Go Unlimited",
           "explanation": "Listen to this music and 50 million more songs with Amazon Music Unlimited.",
           "options": [{"label": "Join Now",
                        "resume": false,
                        "action": "www",
                        "uri": "http://www.amazon.com/gp/dmusic/full-catalog/signup?..."}
                       {"label": "No Thanks",
                        "resume": false}]}}

To handle this error:

  • Display either brief and explanation (e.g. as title and body in a pop-up dialog) or terse if the display has limited space available.
  • explanation may contain html <br> and <a> elements
  • When possible, options should be presented to the user as selectable buttons alongside the error message.
  • When action is www, then selecting the option should open the included uri in a web browser.
  • When action is post, then selecting the option should cause the client to send a post request to the included uri.
  • When action is not present, then selecting the option should dismiss the error message.


Service Availability

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

The Integration Process

Details on service integration requirements can be found on our requirements page.

The following flow chart outlines the integration process:

Content Service Integration Process