Musicovery API v2

Musicovery API v1 documentation available here

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.

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

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. Then you will be able to get similar artist or tracks, and the various types of playlists.
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

    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/V2/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 optional up to 500 requests
    minmatch [0-100] default 30 optional the minimum relevance required (string very similar = close to 100)
    resultsnumber default 50 optional the number of results returned
    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 title track title
    track artist name artist name
    track genre track main genre
    track releasedate year of release
    track album album title
    track version live, remix, performer,...
    track match relevance of the track returned versus the track submitted

    Track get info

    The method returns information about the track: genre, release date, version (remix, live,...), album title, popularity, mood (coordinates).
    You cannot call the method with track string; you need Musicovery track ID; it is a required parameter (if you do not have it, get it from the method Search track).
    Url http://musicovery.com/api/V2/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, optional 2 character international code
    apikey not required 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 title track title
    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 version live, remix, performer,...
    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 coverimg url to display cover art (API key required)
    track sampleurl url to play the sample (API key required)

    Track get similar tracks

    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/V2/track.php
    Parameter Possible values Required/optional Comments
    fct getsimilartracks required code error 300 if missing
    id required Musicovery track id, code error 320 if missing
    tracksnumber default 20 limit 100 optional
    listenercountry us, uk, fr, it, es, de, no 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
    apikey optional up to 500 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 title track title
    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 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/V2/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 500 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 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 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.
    Url http://musicovery.com/api/V2/artist.php
    Parameter Possible values Required/optional Comments
    fct getsimilarartists required code error 400 if missing
    artistmbid required code error 420 if missing
    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 true optional selects similar artists with a popularity higher than 1/100 of the seed artist popularity
    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 name artist name
    artist main genre
    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/V2/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, rap, metal, classical, jazz, cinema, world, latin, reggae, folk, blues, country, vocal pop, disco, gospel, funk, soul 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 name artist name
    artist genre artist genre

    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 languages and tag type can be specified, and used without a tag. If language "en" specified, all tags in English are 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/V2/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 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
    tag name tag name
    tag type tag type
    tag language tag language

    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/V2/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 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/V2/playlist.php

    Playlist from a track

    The method returns a playlist from a 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 genre of the seed track.
    Url http://musicovery.com/api/V2/playlist.php
    Parameter Possible values Required/optional Comments
    fct getfromtrack required code error 600 if missing
    seedtrack required musicovery track id, code error 610 if missing
    resultsnumber [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, es, de, it, no optional country of listener
    stream Boolean default : true optional to get the url to stream the track (API key required)
    userid String optional
    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 title track title
    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 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/V2/playlist.php
    Parameter Possible values Required/optional Comments
    fct getfromartist required code error 600 if missing
    artistmbid required artist Musicbrainz id, code error 620 if missing
    resultsnumber [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 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
    stream Boolean default : true optional to get the url to stream the track (API key required)
    userid String optional
    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 title
    track artist mbid artist MusicBrainz id
    track artist name artist name
    track genre track genre
    track coverimg url to display cover art (API key required)
    track sampleurl url to play the sample (API key required)

    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/V2/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-100] default 20 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 optional 2 digits country code, country of the listener
    stream Boolean default : true optional to get the url to stream the track (API key required)
    userid String optional
    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 title song/track title
    track artist mbid
    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 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/V2/playlist.php
    Parameter Possible values Required/optional Comments
    fct getfrommood required code error 600 if missing
    resultsnumber [0-100] default 15 optional number of tracks in the playlist
    trackvalence [0-1000000] required
    trackarousal [0-1000000] required
    starttrackid Numeric optional Musicovery track id : the first track of the playlist can be specified
    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, rap, metal, classical, jazz, cinema, world, latin, reggae, folk, blues, country, vocal pop, disco, gospel, funk, soul default empty optional genres banned for the playlist separated by commas
    listenercountry 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
    stream Boolean default : true optional to get the url to stream the track (API key required)
    userid String optional
    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 title song/track title
    track artist mbid 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 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/V2/playlist.php
    Parameter Possible values Required/optional Comments
    fct getnewreleases required code error 600 if missing
    listenercountry optional
    resultsnumber [0-100] default 15 optional number of tracks in the playlist
    genreNo rock, electro, pop, randb, rap, metal, classical, jazz, cinema, world, latin, reggae, folk, blues, country, vocal pop, disco, gospel, funk, soul default empty optional genres banned for the playlist separated by commas
    listenercountry optional 2 digits country code, country of the listener
    stream Boolean default : true optional to get the url to stream the track (API key required)
    userid String optional
    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 title song/track title
    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 from location

    The method returns a playlist with songs of artists from the requested location.
    Url http://musicovery.com/api/V2/playlist.php
    Parameter Possible values Required/optional Comment
    fct getfromlocation required code error 600 if missing
    location String required
    listenercountry optional
    resultsnumber [0-100] default 15 optional number of tracks in the playlist
    genreNo rock, electro, pop, randb, rap, metal, classical, jazz, cinema, world, latin, reggae, folk, blues, country, vocal pop, disco, gospel, funk, soul default empty optional genres banned for the playlist separated by commas : rock,electro,pop
    listenercountry optional 2 digits country code, country of the listener
    stream Boolean default : true optional to get the url to stream the track (API key required)
    artistImg Boolean default : true optional get an image of the artist associated with each track
    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 title song/track title
    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)

    User

    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 a API key to use these methods.

    User post info

    This methods collects demographic information on each user.
    Url http://musicovery.com/api/V2/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
    age numeric optional
    gender [m f] optional
    subscriber [true false] default false optional if the user is or has been a subscriber
    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/V2/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/V2/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
    sessionid alphanumerical optional
    objectid required 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/V2/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/V2/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
    trackdid required Musicovery track id
    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/V2/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 (beta)

    This method returns recommendations of tracks, artists, genres for a specific user.
    Url http://musicovery.com/api/V2/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
    resultsnumber [0-20] default 5 optional
    update >Boolean default false optional &update=true recalculates the profile, otherwise returns the last value.
    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 profile (beta)

    This method returns the profile (curious, fan, mainstream, average) and indices (curiosity, diversity) of a specific user.
    Url http://musicovery.com/api/V2/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

    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/V2/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

    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: search
    610 missing or empty parameter: id
    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
    910 at least one of this parameters : location, scale has to be not null
    910 at least one of this parameters : location, scale has to be not null
    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
    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