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",
        "saveplaylists",
        "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.
saveplaylistService supports saving of Audiogum dynamic playlists through the POST /v1/user/{service}/playables/{id} api
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.
shuffleService supports shuffling. When creating an album or playlist playable, it is acceptable to pass "shuffle":true in the playable request
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).
signinmanualcloseService sign-in is not a standard OAuth2 flow and requires the user to manually close the auth web view. Apps should call the POST /v1/user/{service}/token api when the browser is closed. The API will give a 403 if the user cancelled the flow or a 200 if the user linked their account.
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 the user. See Playlists below.
userplaylistscreateService supports creating playlists for the user. See Playlists below.
userplaylistsupdateService supports updating metadata or items in a playlists for the user. See Playlists below.
userplaylistsdeleteService supports deleting playlists for the user. See Playlists below.
userplaylistsitemsaddService supports appending items to playlists for the user. See Playlists below.
userplaylistsitemsdeleteService supports deleting items from playlists for the user. See Playlists below.

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. If a service is not able to respond or times out, an error message will be returned such as:

{
  "type":    "error",
  "error":   "Search request timed out"
}

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.

The Browse API also supports a childitems parameter that allows 'peeking' into the contents of the returned categories - for example on a home-page style view of a service, this allows a more visual view of the browse heirarchy.

APIPurpose
GET /v1/browse/{service}Browse content services.

Where available, the Browse API will provide images returned in an images object and these should be used wherever possible as certification can include checks on this. When images are not available, the 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.

childtheme values

The childtheme values should be used for category browsing when no childtype is available.

NameDescriptionExample Image
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

NameDescriptionExample Image
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 categoriesUse childtheme to derive
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

Using childtheme and childtype

The following example shows how to use childtheme and childtype to derive and image to display. The functions result in a string that can be used to load an embedded asset to display.

  // always use any images returned in preference to this;
  // childtheme / childtype are fall-backs for when there are no images available.

  switch(childtype)
  {
    case "category":
      switch(childtheme)
      {
          case "new":
          case "chart":
          case "featured":
          case "genre":
          case "location":
          case "mood":
          case "personal":
            return "theme_" + childtheme + ".png";
          default:
            // absolute fallback image - e.g. could be app icon or some generic music notes
            return "theme_default.png";
      }
      break;
    case "artist":
    case "album":
    case "single":
    case "song":
    case "playlist":
    case "radioplaylist":
    case "internetradio":
    case "user":
      return "theme_" + childtype + ".png";
    default:
      return "theme_default.png";
  }

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 of content

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 means that the Audiogum platform manages refreshing the service access_token on your behalf and no further action is required to keep access up to date. 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. In some cases, refreshing tokens may not be possible (for example the service has not been used for a long time), in which case the APIs will return a status code 403 - see Errors below.

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. The uri will include a redirect_uri which is used to find the end of the OAuth2 flow and automatically close the web browser. Some services require the user to manually close the browser as they do not offer a full OAuth2 flow.
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. These are provided at 256x256px aimed to be displayed at a smaller size for high density displays.
GET /v1/{service}/playerlogo.pngGet a 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.


Playlists

For services with the userplaylists capability, playlists created by the user on the service can be listed. For creating, updating and deleting playlists, support is denoted by the userplaylistscreate, userplaylistsupdate, userplaylistsdelete, userplaylistsitemsadd and userplaylistsitemsdelete capabilities - see how these map to the APIs below.

Note that Deezer currently does not support setting a description on a user playlist, nor does it allow duplicate songs in a playlist, so appending songs that are already in the playlist will give a 400 error.

APIPurpose
GET /v1/user/{service}/playlistsGets a list of the users' playlists from a service.
Supported on services having userplaylists capability.
POST /v1/user/{service}/playlistsCreates a new user playlist on the service - optionally including items to store in the playlist. A playlist can include a name and for most services, a description.
Supported on services having userplaylistscreate capability.
Additionally, for services supporting userplaylistsupdate, you can optionally specifiy whether to overwrite any existing playlist of the same name, including the items. The items array only need to include the ref of the item from the service.
GET /v1/user/{service}/playlists/{ref}Gets a user playlist on a service - this is a convenience wrapper around the GET /v1/content/{type}/{service}/{ref} API.
Supported on services having userplaylists capability.
POST /v1/user/{service}/playlists/{ref}Appends items to the end of a user playlist on a service. The items array only needs to include the ref of the item from the service.
Supported on services having userplaylistsitemsadd capability.
PUT /v1/user/{service}/playlists/{ref}Updates a user playlist on a service. If the name or description fields differ, these will be updated; if an items array is supplied, these will replace existing items.
Supported on services having userplaylistsupdate capability.
DELETE /v1/user/{service}/playlists/{ref}Deletes a user playlist from a service.
Supported on services having userplaylistsdelete capability.
GET /v1/user/{service}/playlists/{ref}/itemsGets items in a user playlist from a service - this is a convenience wrapper around the GET /v1/content/{parenttype}/{service}/{ref}/{itemtype} API.
Supported on services having listitems capability.
DELETE /v1/user/{service}/playlists/{ref}/itemsDeletes an item from a user playlist on a service.
Supported on services having userplaylistsitemsdelete capability.

Curated Playlists

Setting {service} to curated for the above endpoints creates playlists that are stored on the Audiogum system, not an external music service. These curated playlists allow users to manually build playlists with any content they have access to, since playlist items can be added for any service and ref. The curated service supports the userplaylists, userplaylistscreate, userplaylistsupdate, userplaylistsdelete, userplaylistsitemsadd and userplaylistsitemsdelete capabilities.


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, could not be refreshed 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