Connectez-vous avec votre compte Facebook
 

Differences from MusiclistApi:21 (red) to MusiclistApi:22 (green)

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

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

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 optionLook at [[MusiclistApi_draft]] 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-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.

Examplesrecent documentation 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
Look 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[[MusiclistApi_old]] 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 addsget 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" ==

Thisold 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

}}}that may contain few others informations.