MusiclistApi

You can rollbackto MusiclistApi:10

== 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 ==

=== Get all the albums of the artist named "both" ===

http://www.jamendo.com/get/album/list/artist/page/plain/?names=both

=== Get the name of the album with ID 116 ===

http://www.jamendo.com/get/album/list/album/title/plain/?ids=116

=== Get a RSS feed of the latest torrent links in Ogg Vorbis ===

http://www.jamendo.com/get/album/list/album/p2p/rss2/?o=release_date_desc&p2pnet=bittorrent&are=ogg3


== How are these URLs built? ==

All MusiclistApi URLs follow this simple scheme :

{{{
www.jamendo.com/get/ [itemUnit] /list/ [parametersUnit] / [targetName] / [formatName] / ? ...[parameters]...
}}}

=== 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".

=== 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
* id
* title
* p2p
* audio
* none
* desc1
* archivesrestricted
* name
* artworkurl
* desc3

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-9a-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 secondary params "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 "?order=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.

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


== LOADTYPE = "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),user_rating_desc (for the logged user, best reviews), user_recw_desc (recommendations), needseeding, rating_week_desc, release_date_desc, id_desc, public_date_desc, alpha_desc, needreviews, random
* '''username''' : the username for user_rating_desc or user_recw_desc
* '''n''' : the number of items to fetch
* '''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
* todo, complete this list

== LOADTYPE = "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.

== LOADTYPE = "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

== 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 secondary params "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 secondary params "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 the jamendo.com website.

== Data Model ==
{{{

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





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

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





}}}


== More examples ==

=== Get the album that contains the track with ID 2000 ===

http://www.jamendo.com/get/album/id/track/page/plain/2000/

=== Get all the tracks from the album with ID 33 ===

http://www.jamendo.com/get/track/id/album/audio/plain/33/

=== Get them in the default playlist format ===

http://www.jamendo.com/get/track/id/album/audio/play/33/

=== Get the tracks with IDS 2000 and 2001 in the XSPF playlist format ===

http://www.jamendo.com/get/track/id/track/audio/xspf/2000+2001/

=== Get the 47 latest albums with the tags 'rock' and 'pop' ===

http://www.jamendo.com/get/album/name/tag/page/plain/rock+pop/?n=47&o=release_date_desc

=== Get some informations about the albums with ID 116 and 33, in JSON ===

http://www.jamendo.com/get/album/id/album/data/json/116+33/?ali=info_common

=== Get a list of all the jamendo album IDs ===

http://www.jamendo.com/get/album/list/album/id/plain/?n=all&o=id_asc

=== Get the RSS feed of the latest albums you can use commercially ===

http://www.jamendo.com/get/album/list/album/page/rss2/?o=release_date_desc&cani=c

=== Get the cover of the album 116 ===

http://www.jamendo.com/get/album/id/album/artworkurl/redirect/116/?artwork_size=400

=== GET a list of all Albums with Tag "ROCK" ===

http://www.jamendo.com/get/album/name/tag/page/plain/rock/?n=all

=== GET a list of all Tags of the album 33 ===

http://www.jamendo.com/get/tag/id/album/name/plain/33/?item_o=weight_desc

todo, more examples.