Music Geek Recommendation Service

Overview

Each playlist is generated based on a set of tags. The following types of tags are available

  • Artists – A musical artist or band, for example ‘Neil Young’, ‘Fleetwood Mac’. The resulting playlist will contain songs by artists related to this artist in some way, for example songs in a similar genre by artists who were influenced by the seed artist.
  • Albums – An album, for example ‘Harvest’, ‘Rumours’. The resulting playlist will contain songs that feature musicians or producers who worked on this album.
  • Genres – A musical genre, for example ‘Country’, ‘Blues’. The resulting playlist will contain songs within this genre and its subgenres.
  • Location – A studio, city, state, country etc. For example ‘Abbey Road Studios’, ‘London’. The resulting playlist will contain songs recorded at this location
  • Recording – A song, for example ‘Heart of Gold’, ‘ Go Your Own Way’. The resulting playlist will contain songs related to this song in some way, for example songs with the same genres
  • Time Period – A period of time, currently decades. The resulting playlist will contain songs recorded during this period of time

Each tag has its own ID. Use the Tag Search query to find the ID of the tag you wish to use. Once you have these IDs, you can then pass them into a Playlist query to generate the playlist. Alternatively you can use the Quantone ID of an item to generate a playlist for it.

The number of songs in the playlist can be customized, from a minimum of 1 to a maximum of 20.

Every song comes with metadata, including a number of external IDs to help integrate Music Geek with other services your application uses.

Songs have a reason as to why they were selected. This includes a brief one or two sentence overview, as well as a more detailed statistical breakdown.

Authentication

Authentication Basics

To use the MusicGeek Recommendation Service, you must first register for an AppID and AppKey.

The Recommendation Service is stateless, meaning you must identify yourself with each call. To do this, you will need to include your App ID and App Key in the HTTP request header.

DecibelAppID = { Your App ID } DecibelAppKey = { Your App Key }

Click here for more information on the authentication process

Token Based Authentication

Alternatively you can use token based authentication.

Firstly, send a request for a token to the recommendation service:

https://recommend.quantonemusic.com /Authenticate?appId=YOUR_APP_ID&appKey=YOUR_APP_KEY

Once you have received your token, you can pass it into any query using the token parameter to authenticate yourself without having to modify the HTTP headers of the request.

Each token lasts for 600 seconds.

Searching for Tags

Searching

You can search for a tag by name using the tag search query.

https://recommend.quantonemusic.com/Tags?text=Neil Young

This query would return all the tags that have the name Neil Young.

Alternatively you can restrict your search to only certain types of tags using the tag parameters:

https://recommend.quantonemusic.com/Tags?artists=Neil Young

https://recommend.quantonemusic.com/Tags?albums=Neil Young

The first query would return only the artist tag for Neil Young, whereas the second would return his self-titled debut solo album.

A list of all the special tags, ie Time Period and Catalog tags, can be returned by setting the tagList parameter to true

https://recommend.quantonemusic.com/Tags?tagList=true

A full list of search options can be found here

If none of these are suitable for your use case, you can use the Quantone Data Service to search for artists, albums, locations or recordings using broader terms or external IDs, such as Spotify IDs, and then pass the Quantone ID from these results straight into your playlist query.

For example, you could use the Quantone Data Service to search for all songs recorded at Abbey Studios, take the Quantone IDs of these recordings and then pass them straight to your playlist query.

For more information on using the Quantone Data Service, click here

Dealing with Results

A tag search query returns a collection of tags. Each tag has the following properties

Depending on the type of application you are building, you may wish to pre-load a set of tags to display and prompt the user to select from them to make a playlist. Alternatively, you could use the Quantone Data Service to search for a selected item by another ID. For example, if you are building a Spotify based application, you would let the user select a song from Spotify and then look up the Quantone ID from the Spotify ID of the selected song.

Generating a Playlist

The Playlist Query

Each playlist is generated based on up to 2 given tags. These chosen tags are sent to the MusicGeek Recommendation Service as part of a Playlist query. Each tag should be added to the query as a new parameter.

The size of the playlist can be set as part of the query, up to a maximum of 20 songs. Less songs may be returned if not enough were found to satisfy the given tags.

The example below shows a query for a playlist based on “Neil Young” and “Rock” music with 20 songs.

https://recommend.quantonemusic.com/Playlist?tag=ar-2078c9de-318f-e311-be87-ac220b82800d&tag=gr-05b9df70-6e5a-415d-98ef-786de8a322d6&playlistSize=20

Querying By External ID

By default, the tag parameter accepts only MusicGeek or Quantone IDs. However, you can use IDs from other services by specifying them in the playlist query. This is possible for albums, artists or recordings.

For example, the following will create a playlist based on the album “Black Messiah” by D’Angelo using it’s Spotify ID

https://recommend.quantonemusic.com/playlist?recordingId=spotify:album:5Hfbag0SsHxafx1SySFSX6&recordingIdType=spotify

Tag Combinations

The tags given to the playlist query can be of the same or different types. Any combination is possible, although Time Period tags cannot be used by themselves.

When providing more than one tag, MusicGeek will return a playlist that satisfies all the given tags. For example, using the “George Clinton” and “Funk” tags will give you a playlist of funk songs that are related to George Clinton.

https://recommend.quantonemusic.com/Playlist?tag=ar-bf4488de-318f-e311-be87-ac220b82800d&tag=gr-aa7f3f0c-8043-45fe-b587-8407bc16cd74

If you wanted a playlist of funk songs or songs related to George Clinton, you would run two separate playlist queries.

https://recommend.quantonemusic.com/Playlist?tag=ar-bf4488de-318f-e311-be87-ac220b82800d

This would give you a playlist of songs related to George Clinton

https://recommend.quantonemusic.com/Playlist?tag=gr-aa7f3f0c-8043-45fe-b587-8407bc16cd74

This would give you a playlist of funk music.

Displaying a Playlist

Basic Information

By default, each song in the playlist comes back with the basic information you need in order to display it within your application.

External IDs

A collection of IDs for other services, such as Spotify are Deezer, are returned for most songs recommended by Music Geek. This allows you to integrate Music Geek with other services that your application may use.

These IDs are provided as key value pairs, with the key being the type of ID and the value being the ID itself