Musicovery API v5

Introduction

An API to generate most relevant playlists and recommendations

Musicovery API provides data to generate music recommendations and playlists of all types : from a mood, an artist, a track, a genre/style, a theme, a period/year,...

The response, a list of tracks/artists, can be filtered and personalized with several factors : popularity, listener country, similarity type.

Metadata on tracks (mood, genres, release date,...) and artists (genre, country, debut decade,...) can be queried with the methods track.getInfo and artist.getInfo.

Playlists and recommendations can be dynamically personalized to a specific user. That requires that you post information and behavioural data on that user (see methods below in the user section).

Results can be restricted to a specific track catalog. You must first register the catalog to use this function (see methods in the catalog section).

Ids most used in the industry for tracks and artists (ISRC, Musicbrainz, Spotify, Deezer, 7digital, iTunes, Qobuz, Amazon, Xboxmusic, FNAC, Priceminister, LyricFind, Infoconcert, Francebillet, Digitick) can be used as input and output of the various methods (ex.: you can request an artist radio using Deezer id for the seed artist and get Spotify ids for the tracks of the playlist). See examples below illustrating how to call the API for each method.

You can access freely to Musicovery API. You can query 200 requests in total, that allows you to understand how the API works and test our datas.
Then you need to apply for an API key, which gives you an extra 5000 request allowance.
To query without limitation Musicovery API, you need a Premium API key. To get your API key please contact us at b2b@musicovery.com.
You need first to search IDs for tracks, artists, and tags, using the method Search Track, Search Artist, Search Tags, Search Locations. Then you will be able to get similar artist or tracks, and the various types of playlists and recommendations.
Please read carefully the Terms of use before using Musicovery API.

API Terms of use

Please carefully read this agreement (the "agreement").
Please review these terms and conditions periodically and check the version for changes.
Musicovery will announce changes to the agreement and new releases of the API at https://groups.google.com/forum/#!forum/musicovery-api.
By using Musicovery API and data you explicitly agree to comply with the following Agreement (the "API Terms of service"). If you do not agree to be bound by this agreement, do not use the API.

Musicovery grants you a limited terminable licence to copy and use Musicovery data, subject to the following restrictions:
  • You are entitled to a maximum number of requests to the API: 200 without API key, 5000 with an API key. For more than 5000 requests, you need to obtain a commercial agreement from Musicovery. For a commercial use of Musicovery API or data, contact us at b2b@musicovery.com.
  • In your use of Musicovery data you must comply with all local and international laws and regulations, including intellectual property and data protection laws, and obtain all necessary licences and permissions.
  • You must not transfer any Musicovery data to any country without obtaining consents and authorizations required by law in such country.
  • The user cannot sub-licence Musicovery data to other parties.

    Musicovery may terminate the user access to the API if the preceding conditions are not complied with. In such a case you must immediately discontinue your use of Musicovery API and delete all Musicovery data in your possession.

    When you use Musicovery data you must credit Musicovery and include link to Musicovery API.

    NO WARRANTIES: THE SERVICES AND DATA ARE PROVIDED ON AN "AS IS" BASIS WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  • Forum

    This is the discussion about Musicovery API. You can use this group to ask questions, give feedbacks or suggestions. https://groups.google.com/forum/#!forum/musicovery-api

    Search

    The method returns the possible music objects (tracks, artists, tags, locations) corresponding to the string requested. Certain object types (tracks, artists, tags, locations) can be excluded from the results.
    Results can be restricted to a specific catalog by using the parameter &catalog=.

    If you want to search a track by its artist name and its title, you need to use the method track.search in the “track methods” section below.

    Url http://musicovery.com/api/V5/search.php
    parameter possible values required/optional comments
    fct search required code error 300 if missing
    q required
    artist [true false] default true optional include artists in the answer
    track [true false] default true optional include tracks in the answer
    tag [true false] default true optional include tags in the answer
    location [true false] default true optional include locations in the answer
    partnerid String optional required if the catalogid is specified
    catalogid String optional
    resultsnumber default 50 optional the number of results returned
    format [xml-json] default xml optional the format of the response

    Examples:

    Track methods

    Track search

    The method returns a list of possible tracks, with the following information: artist name, track title, Musicovery track ID, and relevance (match in %).

    You can request the title of a track only, or the title and the artist name, and with a minimum relevance % (parameter &minmatch=).

    Url http://musicovery.com/api/V5/track.php
    parameter possible values required/optional comments
    fct search required code error 300 if missing
    title hey joe required track title (song title)
    artistname Jimi optional the name of the artist/band
    apikey not required up to 200 requests
    minmatch [0-100] default 30 optional the minimum relevance required (string very similar = close to 100)
    partnerid String optional required if the catalogid is specified
    catalogid String optional
    resultsnumber default 50 optional the number of results returned
    bucket id:foreignservice optional to get the results with ids of the following foreignservice=isrc, musicbrainz, spotify, deezer, sevendigital, lyricfind, itunes, amazonmp3, xboxmusic, qobuz, fnac, infoconcert, francebillet, digitick
    format [xml-json] default xml optional the format of the response

    Examples:

    Results

    The API will return the following information ranked by track match decreasing order:
    Data Description
    track id Musicovery track ID
    track foreign id isrc, musicbrainz, deezer, spotify, sevendigital, itunes, qobuz, amazonmp3, xboxmusic
    track title track title
    track subtitle track subtitle
    track work track work
    track genre track main genre
    track releasedate year of release
    track album album title
    track match relevance of the track returned versus the track submitted

    Track get info

    The method returns information about the track: genre, release date, subtitle, album title, popularity, mood (valence and arousal coordinates).

    You cannot call the method with track string; you need Musicovery track ID or a foreign id (isrc, musicbrainz, deezer, spotify, sevendigital, itunes, qobuz, amazonmp3, xboxmusic); it is a required parameter (if you do not have it, get it from the method Search track).

    Url http://musicovery.com/api/V5/track.php
    Parameter Possible values Required/optional Comments
    fct getinfo required code error 300 if missing
    trackid required Musicovery track id, code error 320 if missing
    id foreignservice:track:xxxx ex: deezer:track:5196440 optional foreignservice: isrc, musicbrainz, deezer, spotify, sevendigital, itunes, qobuz, amazonmp3, xboxmusic
    listenercountry us, uk, fr, it, es, ge, it no, wd optional 2 character international code
    bucket id:foreignservice, ex: id:musicbrainz optional to get the results with ids of the following foreignservice: isrc, musicbrainz, deezer, spotify, sevendigital, itunes, qobuz, amazonmp3, xboxmusic
    apikey not required up to 200 requests
    format [xml-json] default xml optional the format of the response

    Examples:

    Results

    The API will return the following information:
    Data Description
    track id Musicovery track ID
    track title track title
    track foreign id isrc, musicbrainz, deezer, spotify, sevendigital, itunes, qobuz, amazonmp3, xboxmusic
    track subtitle track subtitle
    track work track work
    track artist name artist name
    track artist mbid artist Musicbrainz id
    track genre track main genre
    track releasedate year of release
    track album album
    track popularity measured on the scale 1-100 (100=very popular)
    track valence position of the track on the dark/positive scale; integer 1 to 1 000 000; ex.127 239 (API key required)
    track arousal the level of energy of the track; integer 1 to 1 000 000; ex.553 247 (API key required)
    track sampleurl url to play the sample (API key required)

    Track get similar

    The method returns from the requested seed track a list of similar tracks, with the following information: track title, artist name, track ID, genre, distance from the seed track.

    The country of the listener can be specified to ensure there is a good mix of local and international artists in the results (in Musicovery database, the popularity is measured country by country : a hit in Germany, can be a discovery in Italy, and banned in the USA).

    Parameter &similaritytype= enables to finetune the type of similarity (on a scale genre/context, see the example below).
    Parameter &limitgenre= enables to limit the genre of the similar tracks to the seed track's genre.

    Url http://musicovery.com/api/V5/track.php
    Parameter Possible values Required/optional Comments
    fct getsimilar required code error 300 if missing
    id foreignservice:track:xxxx ex: deezer:track:5196440 Required(if partnertrackid not specific) foreignservice: isrc, musicbrainz, deezer, spotify, sevendigital, itunes, qobuz, amazonmp3, xboxmusic
    partnertrackid optional Own track id of the partner
    tracksnumber default 20 limit 100 optional
    listenercountry us, uk, fr, it, es, de, no, wddx_add_vars Default wd optional country as a 2 digit country code
    popularitymax [0-100] optional 100=hit, 0=discovery
    popularitymin [0-100] optional 100=hit, 0=discovery
    similaritytype [0-100] default 60 optional if seed track is genre punk and danceable, 0 will return punk tracks, 100 will return danceable tracks
    limitgenre Boolean default false optional limit the genre of similar tracks to the seed track's genre
    partnerid optional
    catalogid optional
    bucket id:foreignservice, ex: id:musicbrainz optional to get the results with ids of the following foreignservice: isrc, musicbrainz, deezer, spotify, sevendigital, itunes, qobuz, amazonmp3, xboxmusic
    limittobucket [true - false] default false optional limit results to objects available in the foreign id specified by &bucket=
    apikey not required up to 200 requests
    format [xml-json] default xml optional the format of the response

    Examples:

    Response

    The API will return a list of tracks starting with the seed track, with for each track the following information:
    Data Description
    track id Musicovery track ID
    track foreign id isrc, musicbrainz, deezer, spotify, sevendigital, itunes, qobuz, amazonmp3, xboxmusic
    track title track title
    track subtitle track subtitle
    track work track work
    track artist name artist name
    track artist mbid artist Musicbrainz id
    track genre track genre
    track distance 1 to 100 (0= very similar; 100 = little similar)
    track coverimg url to display cover art (api key required)
    track sampleurl url to the sample (api key required)

    Artist methods

    Artist search

    The method returns a list of possible artists, with the following information: artist name, Musicbrainz ID, and relevance (match in %).

    Url http://musicovery.com/api/V5/artist.php
    Parameter Possible values Required/optional Comments
    fct search required code error 400 if missing
    artistname required the name of the artist/band, code error 410 if missing
    bucket id:foreignservice, ex: id:musicbrainz optional to get the results with ids of the following foreignservice: isrc, musicbrainz, deezer, spotify, sevendigital, itunes, qobuz, amazonmp3, xboxmusic
    minmatch [0-100] default 30 optional the minimum relevance required (string very similar = close to 100)
    apikey not required up to 200 requests
    format [xml-json] default xml optional the format of the response

    Example:

    Results

    The API will return the following information order by match desc:
    Data Description
    artist mbid artist Musicbrainz id
    artist foreign id deezer, spotify, sevendigital, itunes, qobuz, amazonmp3, xboxmusic, fnac, priceminister, soundcloud, Instagram
    artist name artist name
    artist genre
    artist country country associated with the artist
    artist decade decade when the artist started to be known
    artist match match in %, 0 to 100 (100 = identical)

    Artist getinfo

    The method returns on the artist the following information: main genre, sub-genre, debut decade, debut year, continent, country, region, city, popularity.

    Url http://musicovery.com/api/V5/artist.php
    Parameter Possible values Required/optional Comments
    fct getinfo required code error 400 if missing
    id musicovery:artist:f467181e-d5e0-4285-b47e-e853dcc89ee7, or foreign ID foreignservice: required Musicovery artist ID or foreignservice ID:deezer, spotify, sevendigital, itunes, qobuz, amazonmp3, xboxmusic, musicbrainz, fnac, priceminister, soundcloud, Instagram code error 320 if missing.
    bucket id:foreignservice, ex: id:musicbrainz optional to get the results with ids of the following foreignservice: isrc, musicbrainz, deezer, spotify, sevendigital, itunes, qobuz, amazonmp3, xboxmusic
    apikey not required up to 200 requests
    format [xml-json] default xml optional the format of the response

    Example:

    Results

    The API will return the following information order by match desc:
    Data Description
    artist mbid artist Musicbrainz id
    artist foreign id deezer, spotify, sevendigital, itunes, qobuz, amazonmp3, xboxmusic, fnac, priceminister, soundcloud, Instagram
    artist name artist name
    artist name2 artist name2
    artist genre artist main genre
    artist genre2 artist sub-genre
    role vocalist, composer,...
    sexe male/female
    decade_debut decade when the artist started to be known
    year_debut year when the artist started to be known
    artist match match in %, 0 to 100 (100 = identical)
    continent
    country
    region
    city

    Examples:

    Artist get similar artists

    The method returns a list of possible artists, with the following information: artist name, Musicbrainz ID, and relevance (%).

    The type of similarity can be weighed according different factors:

  • &focusera=true to get artists from the same era,
  • &focusgenre=true to get artists from the same genre,
  • &obscureartists=false selects artists with a popularity higher than 1/100 of the seed artist popularity.

    The method can also return similar artists to a group of several seed artists.

  • Url http://musicovery.com/api/V5/artist.php
    Parameter Possible values Required/optional Comments
    fct getsimilar required code error 400 if missing
    id foreignservice:artist:xxxx ex: musicovery:artist:f467181e-d5e0-4285-b47e-e853dcc89ee7 required Musicovery artist ID or foreign service ID:deezer, spotify, sevendigital, itunes, qobuz, amazonmp3, xboxmusic, musicbrainz, fnac, priceminister, soundcloud, Instagram. In case of a group of several seed artists, use the coma between 2 artist ids (see example below).
    resultsnumber default 20 limit 100 optional
    popularitymax [0-100] optional 100=hit, 0=discovery
    popularitymin [0-100] optional 100=hit, 0=discovery
    focusgenre [true false] default false optional selects artists very similar in terms of genre
    focusera [true false] default false optional selects artists from the same era
    obscureartists [true false] default false optional selects similar artists with a popularity higher than 1/100 of the seed artist popularity
    bucket id:foreignservice, ex: id:musicbrainz optional to get the results with ids of the following foreignservice: isrc, musicbrainz, deezer, spotify, sevendigital, itunes, qobuz, amazonmp3, xboxmusic
    limittobucket [true - false] default false optional limit results to objects available in the foreign id specified by &bucket=
    apikey not required up to 200 requests
    format [xml-json] default xml optional the format of the response

    Examples:

    Results

    The API will return the following information order by match desc:
    Data Description
    artist mbid artist Musicbrainz id
    artist foreign id deezer, spotify, sevendigital, itunes, qobuz, amazonmp3, xboxmusic, fnac, priceminister, soundcloud, Instagram
    artist name artist name
    artist genre artist main genre
    match artist similarity 0 to 100 (100 = very similar)

    Artist get from location

    The methods returns a list of artists from the requested location.

    Url http://musicovery.com/api/V5/artist.php
    Parameter Possible values Required/optional Comments
    fct getfromlocation required code error 400 if missing
    bucket id:foreignservice, ex: id:musicbrainz optional to get the results with ids of the following foreignservice: isrc, musicbrainz, deezer, spotify, sevendigital, itunes, qobuz, amazonmp3, xboxmusic
    limittobucket [true - false] default false optional limit results to objects available in the foreign id specified by &bucket=
    location required code error 430 if missing
    resultsnumber default 20 limit 100 optional
    genreNo rock, electro, pop, randb, hip hop, metal, classical, jazz, soundtrack, world, latin, reggae, folk, blues, country, vocal pop default empty optional genres banned separated by commas
    apikey optional up to 500 requests
    format [xml-json] default xml optional the format of the response

    Examples:

    Results

    The API will return the following information order by match desc:
    Data Description
    artist mbid artist Musicbrainz id
    artist foreign id deezer, spotify, sevendigital, itunes, qobuz, amazonmp3, xboxmusic, fnac, priceminister, soundcloud, Instagram
    artist name artist name
    artist genre artist main genre

    Artist getusers

    The method returns a list of users most likely to like the requested artist, with a score.

    Url http://musicovery.com/api/V5/artist.php
    Parameter Possible values Required/optional Comments
    fct getusers required code error 400 if missing
    id musicovery:artist:f467181e-d5e0-4285-b47e-e853dcc89ee7, or foreign ID foreignservice: required
    partnerid String optional
    resultsnumber default 20 limit 100 optional
    apikey required
    format [xml-json] default xml optional the format of the response

    Examples:

    Results

    The API will return the following information:
    Data Description
    users user userid
    score

    Tag methods

    Tag search

    The method returns a list of possible tags, with the following information: tag name, tag type (genre, mood, theme, year), language.

    The various translations of a tag are returned.

    Parameters language and tag type can be specified, and used without a tag. If language "en" specified, all tags in English area returned.

    The list of languages currently available are: en (english), es (Spanish), de (German), fr (French), pt (Portuguese), it (Italian), no (Norvegian).

    Url http://musicovery.com/api/V5/tag.php
    Parameter Possible values Required/optional Comments
    fct search required code error 500 if missing
    tag trip-hop, chillout, sad... optional the name of the tag
    type [genre, mood, year, theme] optional the type of the tag
    language [en, es, fr, de, it, pt, no] optional The language of the tag : ex. " variété " in French for " vocal pop "
    apikey not required up to 200 requests
    format [xml-json] default xml optional the format of the response

    Examples:

    Results

    The API will return the following information:
    Data Description
    tag name tag name
    tag type tag type
    tag language tag language

    Tag getfromtime

    The method returns a list of activity tags that are most adequate for the time of the day and day of the week.

    Date and time can be specified.

    Urlhttp://musicovery.com/api/V5/tag.php
    Parameter Possible values Required/optional Comments
    fct getfromtime required code error 500 if missing
    dayoftheweek Monday, Tuesday,... optional
    time 00:00 optional
    listenercountry us, uk, fr, it, es, de, no, wd Default wd optional
    language en, es, fr, de, it, pt, no optional
    apikey not required up to 200 requests
    format [xml-json] default xml optional the format of the response

    Results

    The API will return the following information:
    Data Description
    tag name tag name
    tag type tag type
    tag language tag language

    Example:

    Location

    Location search

    The method returns a list of possible locations with the following information for each results: scale[continent,country,region,city], name

    Url http://musicovery.com/api/V5/location.php
    Parameter Possible values Required/optional Comments
    fct search required code error 600 if missing
    scale [continent, country, region, city] optional scale of the location (continent, country, region, city)
    location optional The location searched
    apikey optional up to 500 requests
    format [xml-json] default xml optional the format of the response

    Examples:

    Results

    The API will return the following information:
    Data Description
    location scale [continent, country, region, city]
    location name location name

    Playlist methods

    There are different types of playlists: generated from a track, an artist, a tag (genre, mood, year, theme), a mood coordinates (valence, arousal), a location, or with new releases.

    They can be personalized to each user by using the parameter &userid= and by posting the user behavioural data via the user methods (post info, post session, post radio, post preference, post play).

    The method playlist.getSmart selects automatically the best playlist type for each user.

    The playlists generated are DMCA compliant (most smart radio licences are using DMCA rules like "no more than 4 songs from the same artist over a period of 3 hours" to limit the level of interactivity allowed for a smart radio).

    Url http://musicovery.com/api/V5/playlist.php

    Playlist from a track

    The method returns a playlist from a seed track. The playlist starts with the seed track, followed by tracks that are similar to it.

    The country of the listener can be specified to ensure there is a good mix of local and international artists in the results (in Musicovery database, the popularity is measured country by country: a hit in Germany, can be a discovery in Italy, and banned in the USA).

    Parameter &similaritytype= enables to finetune the type of similarity on a scale genre/context (see the example below).
    Parameter &limitgenre= enables to limit the genre of the similar tracks to the genre of the seed track.

    Url http://musicovery.com/api/V5/playlist.php
    Parameter Possible values Required/optional Comments
    fct getfromtrack required code error 600 if missing
    id 167394, foreignservice:track:xxxx, deezer:track:5196440 required if partnertrack not specific musicovery track id, code error 610 if missing
    partnertrackid optional Own track id of the partner
    resultsnumber [0-15] default 15
    Premium API key [0-100] default 25
    optional The number of tracks requested in the playlist
    popularitymax [0-100] 100=hit, 0=discovery, default 100 optional The maximum popularity of the tracks of the playlist on a scale 0-100
    popularitymin [0-100] 100=hit, 0=discovery default 25 optional The minimum popularity of the tracks of the playlist on a scale 0-100
    similaritytype [0-100] optional if seed track is genre punk and danceable, 0 will return punk tracks, 100 will return danceable tracks
    listenercountry us, uk, fr, it, es, de, no, wd Default wd optional country of listener
    userid String optional
    bucket id:foreignservice, ex: id:musicbrainz optional to get the results with ids of the following foreignservice: isrc, musicbrainz, deezer, spotify, sevendigital, itunes, qobuz, amazonmp3, xboxmusic
    limittobucket [true - false] default false optional limit results to objects available in the foreign id specified by &bucket=
    partnerid String optional
    catalogid String optional
    apikey optional up to 500 requests
    format [xml-json] default xml optional the format of the response

    Examples:

    Results

    The API will return the following information:
    Data Description
    track id musicovery track id
    track foreign id isrc, musicbrainz, spotify, deezer, sevendigital, lyricfind, itunes, amazonmp3, xboxmusic, qobuz, fnac, infoconcert, francebillet, digitick
    track title track title
    track subtitle track work
    track artist mbid artist MusicBrainz ID
    track artist name artist name
    track genre track main genre

    Playlist from an artist

    The method returns a playlist from a seed artist, with songs from similar artists and from the seed artist.

    The type of similarity can be weighed according different factors :

    &focusera=true to get artists from the same era,
    &focusgenre=true to get artists from the same genre.
    &obscureartists=false selects artists with a popularity higher than 1/100 of the seed artist popularity.

    Url http://musicovery.com/api/V5/playlist.php
    Parameter Possible values Required/optional Comments
    fct getfromartist required code error 600 if missing
    id foreignservice:artist:xxxx, musicbrainz:artist:a74b1b7f-71a5-4011-9441-d0b5e4122711 required artist Musicbrainz id, or foreign ID foreignservice: deezer, spotify, sevendigital, itunes, qobuz, amazonmp3, xboxmusic, fnac, priceminister, soundcloud, Instagram
    resultsnumber [0-15] default 15
    Premium API key [0-100] default 25
    optional The number of tracks requested in the playlist
    popularitymax [0-100] 100=hit, 0=discovery, default 100 optional The maximum popularity of the tracks of the playlist on a scale 0-100
    popularitymin [0-100] 100=hit, 0=discovery default 25 optional The minimum popularity of the tracks of the playlist on a scale 0-100
    listenercountry us, uk, fr, es, de, it, no, wd default wd optional country of listener
    focusgenre Boolean default false optional selects artists very similar in terms of genre
    obscurartists Boolean default false optional selects similar artists with a popularity higher than 1/100 of the seed artist popularity
    userid String optional
    bucket id:foreignservice, id:musicbrainz optional to get the results with ids of the following foreignservice=isrc, musicbrainz, deezer, spotify, sevendigital, itunes, qobuz, amazonmp3, xboxmusic
    limittobucket [true false] default false optional limit results to objects available in the foreign id specified by &bucket=
    partnerid String optional
    catalogid String optional
    apikey not required up to 200 requests
    format [xml-json] default xml optional the format of the response

    Examples:

    Results

    The API will return the following information:
    Data Description
    track id musicovery track id
    track foreign id isrc, musicbrainz, deezer, spotify, sevendigital, itunes, qobuz, amazonmp3, xboxmusic
    track title
    track subtitle
    track work track work
    track artist mbid artist MusicBrainz id
    track artist name artist name
    track genre track genre

    Playlist from a tag

    The method returns a playlist from a tag (genre, mood, year, activity, theme).

    Country of the listener and popularity of tracks can be specified.

    Url http://musicovery.com/api/V5/playlist.php
    Parameter Possible values Required/optional Comments
    fct getfromtag required code error 600 if missing
    tag required code error 630: if missing: The tag is optional if year parameters (yearmin or/and yearmax) are defined
    resultsnumber [0-15] default 15
    Premium API key [0-100] default 25
    optional
    yearmax optional
    yearmin optional yearmin must be < yearmax
    popularitymax [0-100] default 100 optional The maximum popularity of the tracks of the playlist on a scale 0-100, 100=hit, 0=discovery, default 100
    popularitymin [0-100] default 25 optional The minimum popularity of the tracks of the playlist on a scale 0-100, 100=hit, 0=discovery
    listenercountry us, uk, fr, es, de, it, no, wd default wd optional 2 digits country code, country of the listener
    userid String optional
    partnerid String optional
    catalogid String optional
    bucket id:foreignservice, id:musicbrainz optional to get the results with ids of the following foreignservice=isrc, musicbrainz, deezer, spotify, sevendigital, itunes, qobuz, amazonmp3, xboxmusic
    limittobucket [true false] default false optional limit results to objects available in the foreign id specified by &bucket=
    apikey not required up to 200 requests
    format [xml-json] default xml optional the format of the response

    Examples:

    Results

    The API will return the following information:
    Data Description
    track id musicovery track id
    track foreign id isrc, musicbrainz, deezer, spotify, sevendigital, itunes, qobuz, amazonmp3, xboxmusic
    track title song/track title
    track subtitle track subtitle
    track work track work
    track artist mbid
    track artist name artist name
    track genre track main genre

    Playlist from mood coordinates(valence, arousal)

    The method returns a playlist from a given mood. The mood is expressed as mood coordinates : valence and arousal on a scale of 1 - 1,000,000.

    For example a very "calm" and "feeling good" song has the following coordinates: arousal=100,000 and valence=900,000.

    If you want a playlist in the same mood as a given track, get the valence/arousal coordinates of this track with the method "track get info", or "playlist get from a track" with &similartitytype=100.

    To adapt the playlist in terms of listener country, popularity, genres, decades/years, use the corresponding parameters.

    To get a playlist personalized to one particular user, specify the user with the parameter &userid=.

    Url http://musicovery.com/api/V5/playlist.php
    Parameter Possible values Required/optional Comments
    fct getfrommood required code error 600 if missing
    resultsnumber [0-15] default 15
    Premium API key [0-100] default 25
    optional number of tracks in the playlist
    trackvalence [0-1000000] required
    trackarousal [0-1000000] required
    yearmax numeric default 2050 optional
    yearmin numeric default 0 optional yearmin must be < yearmax
    before1950 boolean default true optional
    date50 boolean default true optional
    date60 boolean default true optional
    date70 boolean default true optional
    date80 boolean default true optional
    date90 boolean default true optional
    date00 boolean default true optional
    date10 boolean default true optional
    popularitymax [0-100] default 20 optional The maximum popularity of the tracks of the playlist on a scale 0-100, 100=hit, 0=discovery, default 100
    popularitymin [0-100] default 25 optional The minimum popularity of the tracks of the playlist on a scale 0-100, 100=hit, 0=discovery
    genreNo rock, electro, pop, randb, hip hop, metal, classical, jazz, soundtrack, world, latin, reggae, folk, blues, country, vocal pop default empty optional genres banned for the playlist separated by commas
    listenercountry us, uk, fr, es, de, it, no ,wd default: wddx_add_vars optional 2 digits country code, country of the listener
    tracksversions Boolean default false optional Include a list of altternative versions for the tracks of the playlist
    trackstags Boolean default false optional to get the tags associated with each track
    userid String optional
    bucket id:foreignservice, id:musicbrainz optional to get the results with ids of the following foreignservice=isrc, musicbrainz, deezer, spotify, sevendigital, itunes, qobuz, amazonmp3, xboxmusic
    limittobucket [true false] default false optional limit results to objects available in the foreign id specified by &bucket=
    partnerid String optional
    catalogid String optional
    apikey not required up to 200 requests
    format [xml-json] default xml optional the format of the response

    Examples:

    Results

    The API will return the following information:
    Data Description
    track id Musicovery track id
    track foreign id isrc, musicbrainz, deezer, spotify, sevendigital, itunes, qobuz, amazonmp3, xboxmusic
    track title song/track title
    track subtitle song/track subtitle
    track work song/track work
    track artist mbid MusicBrainz ID
    track artist name artist name
    track genre track main genre

    Playlist get new releases

    The method returns a playlist with new releases.

    To adapt the playlist in terms of listener country and genre use the corresponding parameters.

    Url http://musicovery.com/api/V5/playlist.php
    Parameter Possible values Required/optional Comments
    fct getnewreleases required code error 600 if missing
    popularitymax [0-100] 100=hit,0=discovery default: 100 optional
    popularitymin [0-100] 100=hit,0=discovery default: 25
    listenercountry optional
    resultsnumber [0-15] default 15
    Premium API key [0-100] default 25
    optional number of tracks in the playlist
    genreNo rock, electro, pop, randb, hip hop, metal, classical, jazz, soundtrack, world, latin, reggae, folk, blues, country, vocal pop default empty optional genres banned for the playlist separated by commas
    listenercountry us, uk, fr, es, de, it, no, wd default: wd optional 2 digits country code, country of the listener
    userid String optional
    bucket id:foreignservice, id:musicbrainz optional to get the results with ids of the following foreignservice=isrc, musicbrainz, deezer, spotify, sevendigital, itunes, qobuz, amazonmp3, xboxmusic
    limittobucket [true false] default false optional limit results to objects available in the foreign id specified by &bucket=
    partnerid String optional
    apikey optional up to 500 requests
    format [xml-json] default xml optional the format of the response

    Examples:

    Results

    The API will return the following information:
    Data Description
    track id Musicovery track id
    track foreign id isrc, musicbrainz, deezer, spotify, sevendigital, itunes, qobuz, amazonmp3, xboxmusic
    track title song/track title
    track subtitle song/track subtitle
    track work song/track work
    track artist mbid artist MusicBrainz ID
    track artist name artist name
    track genre track main genre

    Playlist get from location

    The method returns a playlist with songs of artists from the requested location.

    Url http://musicovery.com/api/V5/playlist.php
    Parameter Possible values Required/optional Comment
    fct getfromlocation required code error 600 if missing
    location String required
    listenercountry optional
    resultsnumber [0-15] default 15
    Premium API key [0-100] default 25
    optional number of tracks in the playlist
    genreNo rock, electro, pop, randb, hip hop, metal, classical, jazz, soundtrack, world, latin, reggae, folk, blues, country, vocal pop default empty optional genres banned for the playlist separated by commas : rock,electro,pop
    listenercountry optional 2 digits country code, country of the listener
    bucket id:foreignservice, id:musicbrainz optional to get the results with ids of the following foreignservice=isrc, musicbrainz, deezer, spotify, sevendigital, itunes, qobuz, amazonmp3, xboxmusic
    limittobucket [true false] default false optional limit results to objects available in the foreign id specified by &bucket=
    apikey optional up to 500 requests
    format [xml-json] default xml optional the format of the response

    Example:

    Results

    The API will return the following information:
    Data Description
    track id Musicovery track id
    track foreign id Musicovery isrc, musicbrainz, deezer, spotify, sevendigital, itunes, qobuz, amazonmp3, xboxmusic
    track title song/track title
    track subtitle song/track title
    track work song/track work
    track artist mbid artist MusicBrainz ID
    track artist name artist name
    track genre track main genre
    track coverimg url to display cover art (API key required)
    track sampleurl url to play the sample (API key required)

    Playlist get smart

    The method returns the best playlist at the moment of the request for a given user: taking into account the preferences, history of listening, the day/time, it selects the type of playlists (by activity, mood, artist, track, genre, new releases), and the playlist object (which artists, tracks, genres, era).

    Url http://musicovery.com/api/V5/playlist.php
    Parameter Possible values Required/optional Comment
    fct getsmart required code error 600 if missing
    userid required
    partnerid required code error 1020 if missing
    bucket optional to get the results with ids of the following foreignservice=isrc, musicbrainz, deezer, spotify, sevendigital, itunes, qobuz, amazonmp3, xboxmusic
    limittobucket optional limit results to objects available in the foreign id specified by &bucket=
    resultsnumber [0-15] default 15
    Premium API key [0-100] default 25
    optional number of tracks in the playlist
    apikey optional up to 500 requests
    format [xml-json] default xml optional the format of the response

    Example:

    Results

    The API will return the following information:
    Data Description
    track id Musicovery track id
    track foreign id Musicovery isrc, musicbrainz, deezer, spotify, sevendigital, itunes, qobuz, amazonmp3, xboxmusic
    track title song/track title
    track subtitle song/track title
    track work song/track work
    track artist mbid artist MusicBrainz ID
    track artist name artist name
    track genre track main genre

    User methods

    This group of methods allows:

    • to collect information on each user: demographic data (age, gender, country) and behavioural data (sessions, radios, plays/skips, preferences).
    • to return for each user personalized recommendations, his profile and his last radios.
    You need an API key to use these methods.

    User post info

    This method collects id for a specific user, and optionally his demographic information.

    Url http://musicovery.com/api/V5/user.php
    Parameter Possible values Required/optional Comments
    fct postinfo required code error 1000 if missing
    userid alphanumerical required id of the user
    partnerid alphanumerical required id of the partner posting the info about his user
    country 2 letters country code: ex. it,fr,us optional country of the user
    apikey required
    format [xml-json] default xml optional the format of the response

    Example:

    Response

    Code Comment
    100 valid
    1000 missing or invalid value for parameter: fct accepted values: postinfo, postsession, postuserpreference, postradio,postplay, getlastradios, getrecommendations, getprofile, delete
    1010 missing or invalid value for parameter: userid
    1020 missing or invalid value for parameter: partnerid

    User post session

    This method collects session information of a specific user (date/time, geolocalisation, device type).

    Url http://musicovery.com/api/V5/user.php
    Parameter Possible values Required/optional Comments
    fct postsession required code error 1000 if missing
    sessionid optional if not specified the method returns a sessionid
    userid alphanumerical required if ipaddress and terminalid not specified id of the user
    partnerid required id of the partner posting the info about his user
    ipaddress optional
    terminalid required if userid and ipaddress not specified
    lat format 00.00 optional lattitude
    long format 00.00 optional longitude
    sessiontime date/Time 0000-00-00 00:00 optional date and time of the begining of the session (local time)
    devicetype desktop, phone, tablet, car, watch, other optional
    apikey required
    format [xml-json] default xml optional the format of the response

    Example:

    Response

    Code Comment
    100 valid
    1000 missing or invalid value for parameter: fct accepted values: postinfo, postsession, postuserpreference, postradio, postplay, getlastradios, getrecommendations, getprofile, delete
    1010 missing or invalid value for parameter: userid
    1020 missing or invalid value for parameter: partnerid

    User post preference

    This method collects preferences of a specific user (like and dislikes on tracks, artists, genres).

    Url http://musicovery.com/api/V5/user.php
    Parameter Possible values Required/optional Comments
    fct postpreference required code error 1000 if missing
    userid alphanumerical required id of the user
    partnerid required id of the partner
    partnertrackid optional Own track id of the partner
    sessionid alphanumerical optional
    objectid 167394, deezer:track:5196440 requiredif partnertrackid not specific Musicovery track id, artist mbid, genre
    objecttype [artist, track, genre] required
    objectstatus [like, dislike, neutral] required
    apikey required
    format [xml-json] default xml optional the format of the response

    Example:

    Response

    Code Comment
    100 valid
    1000 missing or invalid value for parameter: fct accepted values: postinfo, postsession, postuserpreference, postradio,postplay, getlastradios, getrecommendations, getprofile, delete
    1010 missing or invalid value for parameter: userid
    1020 missing or invalid value for parameter: partnerid
    1040 missing or invalid value for parameter: objectid
    1050 missing or invalid value for parameter: objecttype accepted values : track, artist, genre
    1060 missing or invalid value for parameter: objectstatus accepted values : like, dislike,neutral

    User post radio

    This methods collects information on the radios launched by a specific user : type of radio (from an artist, a genre, a mood...), seed/object of the radio (the id of the artist if it is an artist radio), and the session id in which it occurred. Beyond radios this method can be used to record the current interest of a user for a specific object (track, artist, genre,...).

    Url http://musicovery.com/api/V5/user.php
    Parameter Possible values Required/optional Comments
    fct postradio required code error 1000 if missing
    userid alphanumerical required id of the user
    partnerid required id of the partner
    sessionid alphanumerical optional
    radiodid optional
    radiotype [artist, track, moodpad, genre, mood, theme, year, new] required a 'moodpad' radio is generated from mood coordinates (valence, arousal); a 'mood' radio is generated from a word (ex.: 'sensual').
    radioobject MusicBrainz artist id, Musicovery track id, arousal/valence coordinates, genre name, theme name, the year as a number required - for an artist radio: &radioobject=artistmbid - for a moodpad radio: &radioobject=valence,arousal - for a track radio: &radioobject=trackid - for a genre radio: &radioobject=genre name - for a theme radio: &radioobject=theme name - for a year radio: &radioobject=year (as a number) - for a new release radio: null
    apikey required
    format [xml-json] default xml optional the format of the response

    Example:

    Response

    Code Comment
    100 valid
    1000 missing or invalid value for parameter: fct accepted values: postinfo, postsession, postuserpreference, postradio,postplay, getlastradios, getrecommendations, getprofile, delete
    1010 missing or invalid value for parameter: userid
    1020 missing or invalid value for parameter: partnerid
    1030 missing or invalid value for parameter: sessionid
    1070 missing or invalid value for parameter: radiotype accepted values : genre, artist, track, mood, year, moodpad, new
    1080 missing or empty value for parameter: radioobject

    User post play

    This method collects information of the ways a track was played (entirely, skipped, removed, interrupted), and in which session and radio it occurred. The 4 play types are:

    • entire: the track is played entirely
    • skipped: the track is skipped before the end, to play the next track in the playlist
    • removed: the track is removed from the playlist proposed
    • interrupted: the track playback is interrupted by the launch of a new playlist, or by the application being closed by the user.
    Url http://musicovery.com/api/V5/user.php
    Parameter Possible values Required/optional Comments
    fct postplay required code error 1000 if missing
    userid alphanumerical optional id of the user
    partnerid required id of the partner
    sessionid alphanumerical required
    radioid alphanumerical optional
    trackid requiredif partnertrack not specific Musicovery track id
    partnertrackid optional Own track id of the partner
    playtype [entire, skipped, interrupted, removed] required
    apikey required
    format [xml-json] default xml optional the format of the response

    Example:

    Response

    Code Comment
    100 valid
    1000 missing or invalid value for parameter: fct accepted values: postinfo, postsession, postuserpreference, postradio,postplay, getlastradios, getrecommendations, getprofile, delete
    1010 missing or invalid value for parameter: userid
    1020 missing or invalid value for parameter: partnerid
    1030 missing or invalid value for parameter: sessionid
    1090 missing or empty value for parameter: trackid
    1095 missing or invalid value for parameter: playtype accepted values : entire, skipped, removed, interruped

    User get last radios

    This method returns the last radios of a specific user.

    Url http://musicovery.com/api/V5/user.php
    Parameter Possible values Required/optional Comments
    fct getlastradios required code error 1000 if missing
    userid alphanumerical required id of the user
    partnerid required id of the partner
    resultsnumber [0-20] default 5 optional number of results per object (artists,track,tag)
    apikey required
    format [xml-json] default xml optional the format of the response

    Example:

    Response

    Code Comment
    100 valid
    1000 missing or invalid value for parameter: fct accepted values: postinfo, postsession, postuserpreference, postradio,postplay, getlastradios, getrecommendations, getprofile, delete
    1010 missing or invalid value for parameter: userid
    1020 missing or invalid value for parameter: partnerid

    User get recommendations

    This method returns recommendations of tracks, artists, genres for a specific user, as well as his burnt tracks and burnt artists (track and artists that he has listened to much).

    Url http://musicovery.com/api/V5/user.php
    Parameter Possible values Required/optional Comments
    fct getrecommendations required code error 1000 if missing
    userid alphanumerical required id of the user
    partnerid alphanumerical required id of the partner
    catalogid alphanumerical optional To restrict recommendation of tracks to a specific catalog
    resultsnumber [0-20] default 5 optional
    allfavorites [true - false] default false optional calculate recommendations using all favorite songs (=true), or a selection (=false)
    update >Boolean default false optional &update=true recalculates the profile, otherwise returns the last value.
    bucket id:foreignservice, id:musicbrainz optional to get the results with ids of the following foreign service=isrc, musicbrainz, deezer, spotify, sevendigital, itunes, qobuz, amazonmp3, xboxmusic
    limittobucket [true false] default false optional limit results to objects available in the foreign id specified by &bucket=
    apikey required
    format [xml-json] default xml optional the format of the response

    Example:

    Response

    Data description
    tracks recommended tracks Musicovery track id for track 1, track 2...
    track foreign ids isrc, musicbrainz, deezer, spotify, sevendigital, itunes, qobuz, amazonmp3, xboxmusic
    Burnt tracks missing or invalid value for parameter: userid
    artists recommended artists Musicbrainz id of artist 1, artist 2,...
    artist foreign ids deezer, spotify, sevendigital, itunes, qobuz, amazonmp3, xboxmusic, fnac, priceminister, soundcloud, Instagram
    Burnt artist
    Recommended genres genre 1, genre 2,...

    Response Codes

    Code Comment
    100 valid
    1000 missing or invalid value for parameter: fct accepted values: postinfo, postsession, postuserpreference, postradio,postplay, getlastradios, getrecommendations, getprofile, delete
    1010 missing or invalid value for parameter: userid
    1020 missing or invalid value for parameter: partnerid

    get new albums

    This method returns a list of new albums personalized for a specific user.

    Url http://musicovery.com/api/V5/user.php
    Parameter Possible values Required/optional Comments
    fct getnewalbums required code error 1000 if missing
    userid alphanumerical required id of the user
    partnerid alphanumerical required Id of the partner getting recommendations for his user
    resultsnumber default: 5 limit: 20 required Id of the partner getting recommendations for his user
    apikey required
    format [xml-json] default xml optional the format of the response

    Example:

    Response

    Data Description
    album title 1
    album title 2
    album title 3

    Error codes

    Code Comment
    100 valid
    1000 missing or invalid value for parameter: fct accepted values: postinfo, postsession, postuserpreference, postradio,postplay, getlastradios, getrecommendations, getprofile, delete
    1010 missing or invalid value for parameter: userid
    1020 missing or invalid value for parameter: partnerid

    User get profile

    This method returns the profile (curious, fan, mainstream, average) and indices (curiosity, diversity) of a specific user.

    Url http://musicovery.com/api/V5/user.php
    Parameter Possible values Required/optional Comments
    fct getprofile required code error 1000 if missing
    userid alphanumerical required id of the user
    partnerid alphanumerical required id of the partner
    apikey required
    format [xml-json] default xml optional the format of the response

    Example:

    Response

    Data Comment
    user profile curious, fan, mainstream, average
    user curiosity indice 1 (not curious) -10 (very curious)
    user diversity indice 1 (focus on 1 genre) -10 (diverse genres)
    user skip rate 0.000 to 1.000

    Error codes

    Code Comment
    100 valid
    1000 missing or invalid value for parameter: fct accepted values: postinfo, postsession, postuserpreference, postradio,postplay, getlastradios, getrecommendations, getprofile, delete
    1010 missing or invalid value for parameter: userid
    1020 missing or invalid value for parameter: partnerid

    User delete

    This method allows a partner to delete the account of one of his user and the corresponding behavioural data (sessions, preferences, radios, plays).

    Url http://musicovery.com/api/V5/user.php
    Parameter Possible values Required/optional Comments
    fct delete required code error 1000 if missing
    userid alphanumerical required id of the user
    partnerid alphanumerical required id of the partner
    apikey required
    format [xml-json] default xml optional the format of the response

    Example:

    Response

    Code Comment
    100 valid
    1000 missing or invalid value for parameter: fct accepted values: postinfo, postsession, postuserpreference, postradio,postplay, getlastradios, getrecommendations, getprofile, delete
    1010 missing or invalid value for parameter: userid
    1020 missing or invalid value for parameter: partnerid

    Catalog methods

    This group of methods allows to register your own catalog of tracks. You first create a catalog (catalog post) and then register the tracks belonging to this catalog (catalog post_track).

    It allows you to use your own track ids as inputs and outputs of methods.

    It also allows you to restrict results to a specific catalog of tracks with all methods using tracks: search, get similar tracks, get playlists, get recommendations.

    Catalog post

    This method creates a catalog.

    Url http://musicovery.com/api/V5/catalog.php
    Parameter Possible values Required/optional Comments
    fct post required code error 1000 if missing
    partnerid alphanumerical required id of the partner
    catalogid alphanumerical optional if not specified the method returns a catalogid
    apikey required API key level 2 required
    format [xml-json] default xml optional the format of the response

    Response

    Data Comment
    Message OK/error_log
    catalogid catalogid (generated by Musicovery if null in the request)

    Examples:

    Catalog delete

    This method deletes a catalog.

    Url http://musicovery.com/api/V5/catalog.php
    Parameter Possible values Required/optional Comments
    fct delete required code error 1200 if missing
    partnerid alphanumerical required code error 1020 if missing
    catalogid alphanumerical optional code error 1205 if missing
    apikey required API key level 2 required
    format [xml-json] default xml optional the format of the response

    Response

    Data Comment
    Message OK/error_log
    catalogid catalogid (generated by Musicovery if null in the request)

    Examples:

    Catalog list

    This method lists the tracks of a catalog.

    Url http://musicovery.com/api/V5/catalog.php
    Parameter Possible values Required/optional Comments
    fct list required code error 1000 if missing
    partnerid alphanumerical required code error 1020 if missing
    catalogid alphanumerical required code error 1205 if missing
    bucket id:musicbrainz, id:foreignservice optional
    apikey required API key level 2 required
    format [xml-json] default xml optional the format of the response

    Response

    Data Comment
    partner_track_id Partner track id
    musicovery_track_id musicovery track id
    foreign_track_id foreign service track id

    Examples:

    Catalog post_track

    This method allows you to add tracks to a catalog. You must have created a catalog first.

    The maximum number of tracks you can add in a catalog is 100,000.

    Url http://musicovery.com/api/V5/catalog.php
    Parameter Possible values Required/optional Comments
    fct post_track required code error 1000 if missing
    partnerid alphanumerical required code error 1020 if missing
    catalogid alphanumerical required code error 1205 if missing
    title required
    artistname required
    partnertrackid required
    apikey required API key level 2 required
    format [xml-json] default xml optional the format of the response

    Response

    Data Comment
    Musicovery track id Musicovery track id if the track was matched
    match match score
    foreign_track_id foreign service track id

    Examples:

    Catalog delete_track

    To delete a track from a catalog.

    Url http://musicovery.com/api/V5/catalog.php
    Parameter Possible values Required/optional Comments
    fct delete_track required code error 1000 if missing
    partnerid alphanumerical required code error 1020 if missing
    catalogid alphanumerical required code error 1205 if missing
    partnertrackid required
    apikey required API key level 2 required
    format [xml-json] default xml optional the format of the response

    Example:

    Additional information

    Response codes

    Code Description
    100 valid
    101 invalid apikey: contact B2B@musicovery.com
    102 1 s. interval for 2 requests reached
    103 too many requests
    104 apikey expired: contact B2B@musicovery.com
    105 missing parameter: apikey, you need a valid apikey
    106 invalid apikey for the partnerid value
    107 invalid apikey for the partnerid value
    300 missing or invalid value for parameter: fct accepted values: search, getinfo, getsimilar
    310 missing or empty parameter: title
    320 missing or empty parameter: id
    400 missing or invalid value for parameter: fct accepted values: search, getsimilar, getfromlocation
    410 missing or empty parameter: artistname
    420 missing or empty parameter: artistmbid
    430 missing or empty parameter: location
    500 missing or invalid value for parameter: fct accepted values: search
    600 missing or invalid value for parameter: fct accepted values: getfromtrack, getfromartist, getfromtag, getfrommood, getnewreleases, getfromlocation
    610 missing or empty parameter: id
    615 This track is not in Musicovery’s database.
    620 missing or empty parameter: artistmbid
    630 missing or empty parameter: tag
    640 missing or empty parameter: location
    700 missing or invalid value for parameter: q
    800 missing or invalid value for parameter: userid
    900 missing or invalid value for parameter: fct accepted values: search
    910 at least one of this parameters : location, scale has to be not null
    1000 missing or invalid value for parameter: fct accepted values: postinfo, postsession, postpreference, postradio, postplay, getlastradios, getrecommendations, getprofile, delete
    1010 missing or invalid value for parameter: userid
    1020 missing or invalid value for parameter: partnerid
    1025 no user found in the DB for userid/partnerid
    1028 session allready defined for the userid/partnerid
    1030 missing or invalid value for parameter: sessionid
    1040 missing or invalid value for parameter: objectid
    1050 missing or invalid value for parameter: objecttype accepted values : track, artist, genre
    1060 missing or invalid value for parameter: objectstatus accepted values : like, dislike,neutral
    1070 missing or invalid value for parameter: radiotype accepted values : genre, artist, track, tag, mood, year, theme, genre, actvity, moodpad, new
    1080 missing or empty value for parameter: radioobject
    1090 missing or empty value for parameter: trackid
    1095 missing or invalid value for parameter: playtype accepted values : entire, skipped, removed, interruped

    Version history

    Version Release date Reatures
    5.0 03.03.2017 addition of tthe methods: artists.getusers, user.getAlbums
    4.0 12.03.2017 addition of catalog methods, method playlist.getsmart and tag.getFromTime, artist.getsimilar with several seed artists.
    3.0 15.10.2015 addition of user, location methods and moodpad playlists
    2.0 20.03.2015 addition of user, location methods and moodpad playlists
    1.0 23.01.2014 release of the initial version with playlist and recommendations

    Older versions

    Musicovery API v1 documentation available here
    Musicovery API v2 documentation available here
    Musicovery API v3 documentation available here