Musicovery API v6


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).

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/V6/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 json 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=).

    Urlhttp://musicovery.com/api/V6/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
    format [xml-json] default json 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 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.

    Url http://musicovery.com/api/V6/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
    listenercountry us, uk, fr, it, es, ge, it no, wd optional 2 character international code
    apikey not required up to 200 requests
    format [xml-json] default json 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 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/V6/track.php
    Parameter Possible values Required/optional Comments
    fct getsimilar required code error 300 if missing
    partnertrackid optional Own track id of the partner
    resultsnumber 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
    apikey not required up to 200 requests
    format [xml-json] default json 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 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)

    Track get similar by audio

    The method returns from the requested seed track a list of similar tracks on the basis of their acoustic similarity, with a similarity score to the seed track. You need to specify the catalog which the seed track will be compared to.

    There a 3 ways to submit the seed track: by using the partnertrackid (&partnertrackid), by using a Youtube url (&youtubeurl), or an url where the audio file can be downloaded (&audiourl).

    Url http://musicovery.com/api/V6/track.php
    Parameter Possible values Required/optional Comments
    fct get_similar_by_audio required code error 300 if missing
    partnertrackid optional Own track id of the partner
    resultsnumber [1-500] default 20 optional
    partnertrackid Required if seedaudiourl and youtubeurl empty
    seedaudiourl Required if partnertrackid and youtubeurl empty
    youtubeurl Required if partnertrackid and seedaudiourl empty
    partnerid optional
    catalogid optional
    apikey not required up to 200 requests
    format [xml-json] default json 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
    partnertrackid
    artist_name
    track_title
    distance The similarity distance to the seed track (0 means identical, 1 very dissimilar)

    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/V6/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
    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 json 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 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/V6/artist.php
    Parameter Possible values Required/optional Comments
    fct getinfo required code error 400 if missing
    id musicovery:artist:f467181e-d5e0-4285-b47e-e853dcc89ee7 required Musicovery artist ID code error 320 if missing.
    apikey not required up to 200 requests
    format [xml-json] default json 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 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/V6/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. 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
    apikey not required up to 200 requests
    format [xml-json] default json 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 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/V6/artist.php
    Parameter Possible values Required/optional Comments
    fct getfromlocation required code error 400 if missing
    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 json 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 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/V6/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 json 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/V6/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 json 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/V6/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 json 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/V6/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 json 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/V6/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/V6/playlist.php
    Parameter Possible values Required/optional Comments
    fct getfromtrack required code error 600 if missing
    id 167394 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
    partnerid String optional
    catalogid String optional
    apikey optional up to 500 requests
    format [xml-json] default json 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 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/V6/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
    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
    partnerid String optional
    catalogid String optional
    apikey not required up to 200 requests
    format [xml-json] default json 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 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/V6/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
    apikey not required up to 200 requests
    format [xml-json] default json optional the format of the response

    Examples:

    Results

    The API will return the following information:
    Data Description
    track id musicovery track id
    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/V6/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
    partnerid String optional
    catalogid String optional
    apikey not required up to 200 requests
    format [xml-json] default json optional the format of the response

    Examples:

    Results

    The API will return the following information:
    Data Description
    track id Musicovery track id
    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/V6/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
    partnerid String optional
    apikey optional up to 500 requests
    format [xml-json] default json optional the format of the response

    Examples:

    Results

    The API will return the following information:
    Data Description
    track id Musicovery track id
    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/V6/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
    apikey optional up to 500 requests
    format [xml-json] default json optional the format of the response

    Example:

    Results

    The API will return the following information:
    Data Description
    track id Musicovery track id
    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/V6/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
    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 json optional the format of the response

    Example:

    Results

    The API will return the following information:
    Data Description
    track id Musicovery track id
    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

    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/V6/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 json 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/V6/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 json 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/V6/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
    apikey required API key level 2 required
    format [xml-json] default json 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/V6/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
    albumname optional
    audio_url optional If the audio file of the track is to be indexed, this parameter is required
    isrc optional
    tag optional
    apikey required API key level 2 required
    format [xml-json] default json 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/V6/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 json optional the format of the response

    Response

    Data Comment
    Mrssage Error/log

    Example:

    Editorial playlist

    This group of methods allows to register editorial playlists (list of tracks selected by you), then get descriptors for each playlist (genres, decades/years, regions, instruments, artist roles...) and get from a given playlist the most similar playlists from your catalog.

    Editorial playlist post

    This method creates an editorial playlist.

    Url http://musicovery.com/api/V6/editorial_playlist.php
    Parameter Possible values Required/optional Comments
    fct post required code error 1000 if missing
    partnerid alphanumerical required id of the partner
    playlist_id alphanumerical optional
    playlist_name alphanumerical optional
    playlist_url alphanumerical optional
    playlist_img_url alphanumerical optional
    apikey required API key level 2 required
    format [xml-json] default json optional the format of the response

    Response

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

    Examples:

    Editorial playlist delete

    This method deletes an Editorial playlist.

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

    Response

    Data Comment
    Message OK/error_log

    Examples:

    Editorial_playlist list

    This method lists the editorial playlists for a partner

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

    Response

    Data Comment playlist_id id of the playlist playlist_name name of the playlist playlist_url/td> url of the playlist playlist_img_url/td> image associated to the playlist

    Examples:

    Editorial playlist post_track

    This method allows you to add tracks to an editorial playlist. You must have created an editorial playlist first.

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

    Response

    Data Comment
    track_id track_id (generated by Musicovery if null in the request)

    Examples:

    Editorial playlist delete_track

    To delete a track from an editorial playlist.

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

    Example:

    Editorial_playlist tracks list

    This method lists the tracks of an editorial playlist.

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

    Response

    Data Comment
    message Ok/Error Log

    Examples:

    Editorial playlist get similar playlists

    This method gets from a given editorial playlist the most similar editorial playlists from the catalog you registered on the API.

    Url http://musicovery.com/api/V6/editorial_playlist.php
    Parameter Possible values Required/optional Comments
    fct getsimilar required code error 400 if missing
    playlist_id required
    apikey not required up to 200 requests
    format [xml-json] default json optional the format of the response

    Response

    The API will return the following information by match decreasing order:

    Data Description
    playlist_id id of the playlist
    playlist_name name of the playlist
    playlist_url url of the playlist
    playlist_img_url image associated to the playlist
    match playlist similarity (0 - 100

    Examples:

    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 Features
    6.0 10.01.2019 addition of the group of methods editorial playlists, and the method get similar tracks by audio.
    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
    Musicovery API v3 documentation available here
    Musicovery API v3 documentation available here