Purpose

This powerful RESTful API allows you to fetch any data related to the music on jamendo. It is read-only. It is currently the most used Jamendo API. It is also accessible from Ajax and XML-RPC.

Things you can query with this API : albums, artists, tracks, users, tags, playlists, reviews, ...

A few basic examples

For more examples, see MusiclistApiExamples

How are these URLs built?

All MusiclistApi URLs follow this simple scheme :

www.jamendo.com/get/ [itemUnit] / [loadtype] / [parametersUnit] / [targetName] / [formatName] / ? ...[secondaryParameters]...

itemUnit

This is the type of the items you will get back. Valid values are :

album
track
artist
review (experimental)
user (experimental)
tag (experimental)

For instance, when loading a playlist, itemUnit will be "track". But if you want to find all the artists that meet some criteria, it will be "artist".

loadtype

id

Use this option to get data associated to IDs you already know. Several IDs can be fetched in a new primary param, separated by "+" (equivalent to spaces in the urls)

For instance, if you want to get the albums of the groups with ids "both" and "triface" :

http://www.jamendo.com/get/album/id/artist/page/plain/both+triface/

list

This one is the most complicated. Use it to get a list of data with some optional secondary params :

'''o''' : the order. can be one of : rating_desc (global popularity, default), rating_asc, rating_week_desc (for 1 week), user_rating_desc (for the logged user, best reviews), user_recw_desc (recommendations), needseeding, release_date_desc, date_desc, date_asc, id_desc, public_date_desc, alpha_desc, track_no_desc, needreviews, random
'''username''' : the username for user_rating_desc or user_recw_desc
'''n''' : the number of items to fetch (or all)
'''pn''' : the page number. default to 1. The items will be fetched in the range (n*(pn-1)) to (n*pn).
'''l''' : A 3-letter ISO country code.
'''tag''' : a jamendo tag
'''aclass''' : album class. "2" for long albums, "3" for short albums. You can fetch both with "2,3"
'''cani''' : rights on the music. "c" for allowed commercial use, "d" for allowed derivatives, "cd" for both
'''subset''' : user_dl (albums previously downloaded), user_listened (albums listened to), user_star (starred albums), user_lowfi (listened in stream), user_notlistened, user_recom, user_view (albums viewed on jamendo.com/album/xxx/)
'''subset_user_id''' : user_id for the subsets above
'''tri, ali, ari, tgi, rri, uri, pli''' : tri means track identifier. al album, ar artist, tg tag, rr review, ur user, pl playlist. Should be info_min or info_common or full.
todo, complete this list.

recom

Use this to get the music recommendations for the user currently logged. You'll need to use the jamendo cookie authentification. It adds a "n=xx" secondary parameter where xx is the number of recommendations you want to fetch.

tag

This is an alias for LOADTYPE=list with a secondary param tag=xxx.

For instance,

http://www.jamendo.com/get/album/tag/album/page/plain/electronica

is the same as

http://www.jamendo.com/get/album/list/album/page/plain/?tag=electronica

parametersUnit

Same valid values as itemUnit.

If you want to get all the albums of the artist with ID=5, itemUnit will be "album" and parameterUnit will be "artist".

You may specify multiple parametersUnits (see below).

If you query is simple you can have itemUnit=parameterUnit. ("get the album with albumid=33")

targetName

Valid values are:

page : returns page url
id : returns item id
title : returns the title of the item
p2p : returns BitTorrent or Emule tracker
audio : returns url of the stream
none
desc1 : returns complete description of the item
desc2 : returns partial description of the item
desc3 : returns minimalist description of the item
archivesrestricted
name : if exists, returns the name of the item
artworkurl : returns covers of an album/track (see below)

Target is the content you are looking for. For a list of IDs use "id". For a playlist use "audio".

formatName

This API supports a wide range of output formats. Valid values are:

plain
rss2
json
podcast
play
xspf
ram
smil
pls
m3u
(xmlrpc)
ahah
redirect
phpserialized

Any ideas on new ones ? ;-)

Jamendo IDs

There are 3 different types of IDs on jamendo :

album IDs : Numeric, you can see them in the URLs of the albums : For album 33 the URL is http://www.jamendo.com/album/33/
track IDs : Numeric, you can see them in the URLs of the streams.
artist IDs : Numeric, they are invisible in the jamendo website because we use artist names instead in the URLs.

Artist IDs / Names / Dispnames

Artist IDs : See above
Artist Names : Unique string, with no special characters ([0-9^a-z.-]). They are used in the URLs (for instance : http://www.jamendo.com/artist/both/ for the artist with name "both").
Artist Dispnames : The "real" artist name, not unique. Most often it's the same as above, but it can be competely different.

Examples of id / name / dispname :

22 / acoustic.affinites / Acoustic Affinités
5 / both / Both

Redirections

Any application implementing this API should be ready to follow HTTP redirections.

List of audio encodings

The valid values for the secondaryParameters "aue" and "are" are :

"ogg1" : lowfi OGG (q-1)
"ogg2" : lowfi OGG q4
"ogg3" : hifi OGG q7
"mp31" : lowfi MP3 (96kbits) (default for streaming / player)
"mp32" : hifi MP3 (200kbits+) (default for archives)

Please note that currently you can only use the lowfi for streaming and the hifi in the P2P archives.

Some incompatible options

There are a few dead ends in the API. For instance, you can't use TARGETUNIT=artist and TARGET=p2p, because we don't have per-artist archives. With TARGET=p2p currently you must use TARGET=album.

Same thing for TARGET=audio.. TARGETUNIT must be "track".

XMLRPC entry point

You can query the Music API with XMLRPC at this address : http://www.jamendo.com/xmlrpc/

There is only one method : '''array jamendo.get(string primaryparams, struct secondaryparams)'''

primaryparams is the "TARGETUNIT/LOADMETHOD/PARAMUNIT/TARGET/FORMAT/..." string you know from the API urls.
secondaryparams is a struct with the params that you would pass in the url, for instance "?o=xxx&tag=yyy" will become {"order":"xxx","tag":"yyy"} in an xmlrpc struct.

Please set TARGET to "xmlrpc". you can test queries in your brower with this format, too.

For instance, a query to : http://www.jamendo.com/get/track/id/album/audio/xmlrpc/33+45/?audio_encoding=ogg2

translates to this XMLRPC request : '''jamendo.get("track/id/album/audio/xmlrpc/33+45/",{"audio_encoding":"ogg2"})'''

Special cases

In this section we'll highlight several interesting options that require some additional parameters.

TARGET = "audio"

This will target to our http audio files. It adds the secondary param "aue=xxx" where xxx is the name of the audio encoding (see above).

TARGET = "p2p"

This will target our P2P archives. It will point to to a torrent file or to an ed2k link. It adds the secondaryParameters "p2pnet" and "are".

"p2pnet" can be "torrent" (default) or "ed2k".

"are" is the archive audio encoding. (see formats above)

TARGET = "artworkurl"

This will target the cover of an album/track. TODO artist images. It adds the secondaryParameters "artwork_size" and "artwork_id".

"artwork_size" is an integer. The covers are available for 70,100,130,200,300,400, etc. If you want a custom one, mail us.

TARGET = "data"

todo

FORMAT = "play"

This one is an alias for the default playlist format of the currently logged user. It defaults to "m3u". It is widely used on Jamendo.

Data Model

One to One :     ------
One to Many :    -----*
Many to Many :   *----*         

 Concert *-----* Artist *-----* User
                   |
                   |
                   *      

  Review *----*  Album  *------* Tag *-------* User
     *                   
     |             |              *
   User            |              |
                   |              |
                   *              *
 License ------* Track *------* Playlist *-------User