▼Differences from MusiclistApi:19 (red) to MusiclistApi:20 (green)
You can rollbackto MusiclistApi:19
== Draft ==
== 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* Pattern 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 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 needURL 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
{{{www.jamendo.com/get/[itemUnit]/[loadtype]/[parametersUnit]/[targetName]/[formatName]/<value><?param><¶m>...}}}
* 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. ValidMultiple 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 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 APIsepared 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.| **Parameter** | **Description** | **Values** |
| itemUnit/parametersUnit | target item/source item | album, artist, track, tag, user ; //secondary :// playlist, review, news |
| loadtype | | **list** ; //older (still use) :// id, name ; //older (unused) :// recom, tag |
| targetName | target type | id, data, name, title, page (url), p2p (tracker), audio (stream url) ; //secondary :// none, desc{1,2,3} ({full,common,min} description), archivesrestricted, artworkurl (cover) |
| formatName | target format | plain, rss2 (rss 2.0), {pretty,}json, podcast, play, xspf, ram, smil, pls, m3u, xmlrpc, ahah, redirect, phpserialized |
| param | tarjet and/or source parameters | see //parameters// section |
Please set TARGETOnly **list** loadertype will be maintained in futures versions of this API. It allows you to "xmlrpc".get everthing you can test queries in your brower withwant. It's advised to use only this format, too.since it limits misunderstanding of API by comparaison to other loadertypes.
For instance, a query to : http://www.jamendo.com/get/track/id/album/audio/xmlrpc/33+45/?audio_encoding=ogg2=== Examples ===
translates to this XMLRPC requestFirst simple examples : '''jamendo.get("track/id/album/audio/xmlrpc/33+45/",{"audio_encoding":"ogg2"})'''
= Special cases =| Both's Albums | http://www.jamendo.com/get/album/list/artist/title/plain/?names=both |
| Both's Albums | http://www.jamendo.com/get/album/list/artist/page/plain/?names=both |
| album with albumid=116 | http://www.jamendo.com/get/album/list/album/title/plain/?ids=116 |
| Tags of ablumid=116 | http://www.jamendo.com/get/tag/list/album/name/plain/?ids=116 |
| 50 Albums ids | http://www.jamendo.com/get/album/list/album/id/plain/?n=50&o=id_asc |
| latest album's RSS feed that you can use commercially | http://www.jamendo.com/get/album/list/album/page/rss2/?o=release_date_desc&cani=c |
In this section we'll highlight several interesting options that require some additional parameters.
== Built your URLs ==
== TARGET = "audio" ==Only **list** loadertype will be maintained in futures versions of this API. It allows you to get everthing you want. It's advised to use only this since it limits misunderstanding of API by comparaison to other loadertypes.
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).Get your own requests by reading next //Parameters// section :
== TARGET = "p2p" ===== List of parameters ===
This will target our P2P archives. It will pointYou can use some optional secondary params to to a torrent file or to an ed2k link. It adds the secondaryParameters "p2pnet" and "are".get what you want :
"p2pnet" can| **Parameter** | **Should be "torrent" (default) or "ed2k".used with** | **Can be used with** |
| identifier | //optional// | list //loadertype// |
| order | //optional// | all |
| number | //optional// | all |
| //item// information | desired //item// | all (may no add any information depending of //source item//) |
| User id | //optional// | user, playlist, review //items// |
| Artwork | album, track //source item// & artworkurl //target item// | N/A |
| Stream encoding | audio //target item// | N/A |
| P2P | album //item// & p2p //target item// | tracker parameter & others //target item// |
| show / hide | //optional// | |
| SubSettings | //optional// | |
| Others | //optional// | |
"are" is the archive audio encoding. (see formats above)=== Values of parameters ===
== TARGET = "artworkurl" ==Here are the values you can use with these parameters :
This will target| **Parameter** | **code** | **value** | **description** |
| identifier | ids, names | //value// | Numerical, name is an unique string with no special characters ([0-9a-z.-]) |
| order | o | rating_desc | global popularity, default |
| | | user_rating_desc | for the coverlogged user, best reviews |
| | | rating_week_desc | |
| | | release_date_desc | |
| | | date_desc | |
| | order (diff ??) | rating_week_desc | |
| | item_o (diff ??) | track_no_asc | |
| | | random | |
| number | n | //value// | number of item to get back |
| Album info | ali | min (default) | id |
| | | info_min | //add to previous// name, artist_id, archive_set |
| | | info_common | //add to previous// lengths, release_date, public_date, class, com_level, buyurl, filename, imagenum, status, mod, license_id, license_music_multiple, license_artwork_id, review_num, review_note, review_num_week, review_note_week, public_date_f, release_date_f, length_total |
| | | full | //add to previous// genre_str, genre_str_lang, desc_str, desc_str_lang, referrer_count, playlisted_count, lowfi_count, favourited_count, tracker_seeds_num, tracker_clients_num, tracker_finished_num, upload_date, validation_date, relance_date, id3genre, validation_url, root_audio, root_images, root_torrents, images{}, desc_html, archives{}, certif{} |
| | | desc | description |
| | | images | //Don't work// |
| | | archives | link to download |
| | | tracker | status of tracker (use with aenc) |
| | | genre | tags |
| Artist info | ari | min (default) | id |
| | | info_min | //add to previous// name, dispname |
| | | info_common | //add to previous// homepage, date_start, date_join, date_end, image |
| | | full | //add to previous// genre_str, genre_str_lang, desc_str, desc_str_lang, creator_user_id, forum_id, pays, departement, ville, desc_html, geo_countryname, geo_str1, relationjam{} |
| | | desc | //add// desc_str, desc_str_lang, desc_html |
| | | geo | //add// pays, departement, ville, id, geo_countryname, geo_str1 |
| Playlist info | pli | //any// (default) | name, id, public, user_id, albumcount |
| Review info | rri | min (default) | id |
| | | info_min | //add to previous// title, album_id, user_id, note1, agree_cnt, pubdate, pubdate_f, review_link |
| | | info_common | //add to previous// lang, reply_topic_id, reply_topic_lang, blog_id, blog_link, blog_exclusive, reply_link, num_replies |
| | | full | //add to previous// review_text, date |
| User info | uri | min (default) | id |
| | | info_min,info_common | //add to previous// name, profile_link |
| | | full | //add to previous// avatar, pays, departement, has_transperm, inscr_date, avatarurl, classes{}, classes_html |
| | | avatar | //add// avatar, avatarurl |
| Tag info | tgi | min (default) | id |
| | | info_common,full | //add to previous// name |
| Track info | tri | min (default) | id |
| | | info_min | //add to previous// album_id, name, track_no |
| | | info_common | //add to previous// lengths, filename, com_level, parental_level, license_id |
| | | full | //add to previous// lyrics_text, lyrics_exists, lyrics_lang, lyrics_mod_date, id3genre, length |
| User id | uid | //value// | Select info related to an album/track. TODO artist images. It adds the secondaryParameters "artwork_size" and "artwork_id".user |
| Stream encoding | aue (audio enc) | ogg1, ogg2, mp31 | lowfi OGG (q-1), lowfi OGG q4, lowfi MP3 (96kbits) (default for streaming / player) |
| P2P | p2pnet | torrent (default), ed2k | use with target p2p |
| | aenc,are (archive enc : tracker | ogg3, mp32 | hifi OGG q7, hifi MP3 (200kbits+) |
| Artwork | artwork_size | //value// | 70,100,130,200,300,400, etc (mail us for get a custon one) |
| | artwork_id | //value// | |
| show / hide | item_showhidden | 1, 2, //other// (default) | all albums, albums.status<>'V', albums.status='V' |
| | shownotmod | 1, 2, //other// (default) | all albums, albums.`mod`=0, albums.`mod`=1 |
| | item_nid | $previous_ids | |
| SubSettings | subset | user_star | |
| | item_subset | user_notign, user_notlater, user_star | |
| Others | item_program | 13 | artist_revenueshare |
| | json_iddict | 1 | change Json format from [{"id":1234}] to {"1234":{"id":1234}} (example of result) |
| | item_nids | $previous_ids | |
| | displangs | $rl | |
"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.=== More Examples ===
== TARGET = "data" ==| **Description** | **Url example** |
| 5 latest ablums released (minimal information) | http://www.jamendo.com/get/album/list/album/data/json/?n=5&o=release_date_desc&ali=info_min |
| All album info and common artist info of the first album released | http://www.jamendo.com/get/album/list/album/data/json/?n=1&o=release_date_asc&ali=full&ari=info_common |
| Ids of album by "both" artist | http://www.jamendo.com/get/album/list/artist/data/json/?names=both |
| Tags of album which id is 33 | http://www.jamendo.com/get/tag/list/album/data/json/?ids=33&tgi=info_common |
| Complete user info | http://www.jamendo.com/get/user/list/user/data/json/?names=sylvinus&uri=full |
todo== Others ==
== FORMAT = "play" ===== Other Loadertypes ===
This one is an alias for the default playlist format of the currently logged user. It defaults to "m3u". It is widelyThese Loadertypes are still used on Jamendo.Jamendo portal and [[JamendoApps]]. They are a bit shorter to write.
== Data Model ==There is a description of used URL on Jamendo portal :
{{{| **Description** | **Url example** |
| Get //item// from **name** of other //item// | **name** loadertype |
| album id from artist (name) | http://www.jamendo.com/get/album/name/artist/id/json/both/?n=all&item_program=&album_shownotmod=1&album_showhidden=1 |
| artist id | http://www.jamendo.com/get/artist/name/artist/id/json/both/ |
| //parameters// | http://www.jamendo.com/get/artist/name/artist/id/json/both/?n=all&item_shownotmod=1&item_showhidden=1 |
| restrict geo area | http://www.jamendo.com/get/artist/name/artist/id/json/both/?geo=all |
| track id from artist | http://www.jamendo.com/get/track/name/artist-album/id/json/both/ |
| //parameters// | http://www.jamendo.com/get/track/name/artist-album/id/json/both/?n=all&item_program=&album_shownotmod=1&album_showhidden=1 |
| artist info | http://www.jamendo.com/get/artist/name/artist/data/json/both/?ali=&ari=full&tri= |
| albums info from artist name | http://www.jamendo.com/get/album/name/artist/multi/json/both/?targets=id+desc2&n=all&album_shownotmod=1&album_showhidden=1 |
| Get //item// from **id** of other //item// | **id** loadertype |
| user name (from his id) | http://www.jamendo.com/fr/get/user/id/user/name/plain/2 |
| tag name | http://www.jamendo.com/get/tag/id/tag/name/plain/23 |
| tag name from album | http://www.jamendo.com/get/tag/id/album/name/json/33?item_o=weight_desc&n=5 |
| album id from artist (id) | http://www.jamendo.com/get/album/id/artist/id/json/5/?item_program=13&item_shownotmod=0&item_showhidden=0 |
| album from tag (error rating!) | http://www.jamendo.com/get/album/id/tag/id/json/23?o=rating_desc&countall=1 |
| albums info from album | http://www.jamendo.com/get/album/id/album/data/json/33?ali=info_common&ari=info_common |
| artist(param) and album infos | http://www.jamendo.com/get/album/id/album/data/json/33/?ali=full+object&ari=full+object&tri= |
| tracker info (for specified enc) | http://www.jamendo.com/get/album/id/album/data/json/33?ali=info_min+archives+tracker&ari=info_min&aenc=ogg3 |
| albums info from artist | http://www.jamendo.com/get/album/id/artist/data/json/5/?ali=info_min&n=all |
| //parameters// | http://www.jamendo.com/get/album/id/artist/data/json/5?ali=full&ari=full+object&item_showhidden=1&item_shownotmod=1 |
| artist info (description) | http://www.jamendo.com/get/artist/id/artist/data/json/5?ari=desc+info_common |
| news info from user | http://www.jamendo.com/get/news/id/user/data/json/2?nwi=info_common&n=50&item_o=id_desc&item_showmailed=1&item_showviewed=1 |
| playlist info | http://www.jamendo.com/get/playlist/id/playlist/data/json/?pli=full&uri=info_min |
| review info | http://www.jamendo.com/get/review/id/review/data/json/4844?rri=full&class=review&displangs=current&o=date_desc |
| | http://www.jamendo.com/get/ringtone/id/ringtone/data/json/?rgi=file |
| tag info | http://www.jamendo.com/get/tag/id/tag/data/json/23?tgi=full |
| track info from album | http://www.jamendo.com/get/track/id/album/data/json/33?ali=full&ari=full+object&tri=full&item_o=track_no_asc&showhidden=1&shownotmod=1 |
| //parameters// | http://www.jamendo.com/get/track/id/album/data/json/33?ali=full&ari=info_common&tri=info_common |
| track info from playlist | http://www.jamendo.com/get/track/id/playlist/data/json/4681/?n=all&tri=info_min |
| user info | http://www.jamendo.com/get/user/id/user/data/json/2?uri=info_min+avatar |
| « Album : review title » | http://www.jamendo.com/get/review/id/review/desc2/json/4844?ali=info_common+images&rri=full |
| | http://www.jamendo.com/get/track/id/track/datasmall/json/1234/?json_iddict=1 |
One to One=== FIXME : ------
One to Many : -----*
Many to Many : *----* remove ===
Concert *-----* Artist *-----* User
|
|
* What association can be done ?
Review *----* Album *------* Tag *-------* User
*
| | *
User | |
| |
* *
License ------* Track *------* Playlist *-------UserCaption :
* **A/A/T** : Something of album, artist, track
* **** page, tag, //etc//.
}}}| **Meaning** | / [itemUnit] | / [loadtype] | / [parametersUnit] | / [targetName] | / [formatName] | ?[parameters] |
| Title of //**A/A/T**// of artist named //sbdy// | //**A/A/T**// | list | artist | title | plain | name=//sbdy// |
| Page of //**A/A/T**// of artist named //sbdy// | //**A/A/T**// | list | artist | page | plain | name=//sbdy// |
| Title of //**A/A/T**// identified with //**A/A/T**2//'s //id// | //**A/A/T**// | list | //**A/A/T**2// | title | plain | ids=//id// |
| Tags name of //**A/A/T**// identified with his //id// | tag | list | //**A/A/T**// | name | plain | ids=//id// |
| Ids of //**A/A/T**// | //**A/A/T**// | list | //same as first **A/A/T**// | id | plain | //other options// |
| RSS field | album | list | album | page | rss2 | //other options// |
== 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* Pattern 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 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 needURL 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
{{{www.jamendo.com/get/[itemUnit]/[loadtype]/[parametersUnit]/[targetName]/[formatName]/<value><?param><¶m>...}}}
* 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. ValidMultiple 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 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 APIsepared 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.| **Parameter** | **Description** | **Values** |
| itemUnit/parametersUnit | target item/source item | album, artist, track, tag, user ; //secondary :// playlist, review, news |
| loadtype | | **list** ; //older (still use) :// id, name ; //older (unused) :// recom, tag |
| targetName | target type | id, data, name, title, page (url), p2p (tracker), audio (stream url) ; //secondary :// none, desc{1,2,3} ({full,common,min} description), archivesrestricted, artworkurl (cover) |
| formatName | target format | plain, rss2 (rss 2.0), {pretty,}json, podcast, play, xspf, ram, smil, pls, m3u, xmlrpc, ahah, redirect, phpserialized |
| param | tarjet and/or source parameters | see //parameters// section |
Please set TARGETOnly **list** loadertype will be maintained in futures versions of this API. It allows you to "xmlrpc".get everthing you can test queries in your brower withwant. It's advised to use only this format, too.since it limits misunderstanding of API by comparaison to other loadertypes.
For instance, a query to : http://www.jamendo.com/get/track/id/album/audio/xmlrpc/33+45/?audio_encoding=ogg2=== Examples ===
translates to this XMLRPC requestFirst simple examples : '''jamendo.get("track/id/album/audio/xmlrpc/33+45/",{"audio_encoding":"ogg2"})'''
= Special cases =| Both's Albums | http://www.jamendo.com/get/album/list/artist/title/plain/?names=both |
| Both's Albums | http://www.jamendo.com/get/album/list/artist/page/plain/?names=both |
| album with albumid=116 | http://www.jamendo.com/get/album/list/album/title/plain/?ids=116 |
| Tags of ablumid=116 | http://www.jamendo.com/get/tag/list/album/name/plain/?ids=116 |
| 50 Albums ids | http://www.jamendo.com/get/album/list/album/id/plain/?n=50&o=id_asc |
| latest album's RSS feed that you can use commercially | http://www.jamendo.com/get/album/list/album/page/rss2/?o=release_date_desc&cani=c |
In this section we'll highlight several interesting options that require some additional parameters.
== Built your URLs ==
== TARGET = "audio" ==Only **list** loadertype will be maintained in futures versions of this API. It allows you to get everthing you want. It's advised to use only this since it limits misunderstanding of API by comparaison to other loadertypes.
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).Get your own requests by reading next //Parameters// section :
== TARGET = "p2p" ===== List of parameters ===
This will target our P2P archives. It will pointYou can use some optional secondary params to to a torrent file or to an ed2k link. It adds the secondaryParameters "p2pnet" and "are".get what you want :
"p2pnet" can| **Parameter** | **Should be "torrent" (default) or "ed2k".used with** | **Can be used with** |
| identifier | //optional// | list //loadertype// |
| order | //optional// | all |
| number | //optional// | all |
| //item// information | desired //item// | all (may no add any information depending of //source item//) |
| User id | //optional// | user, playlist, review //items// |
| Artwork | album, track //source item// & artworkurl //target item// | N/A |
| Stream encoding | audio //target item// | N/A |
| P2P | album //item// & p2p //target item// | tracker parameter & others //target item// |
| show / hide | //optional// | |
| SubSettings | //optional// | |
| Others | //optional// | |
"are" is the archive audio encoding. (see formats above)=== Values of parameters ===
== TARGET = "artworkurl" ==Here are the values you can use with these parameters :
This will target| **Parameter** | **code** | **value** | **description** |
| identifier | ids, names | //value// | Numerical, name is an unique string with no special characters ([0-9a-z.-]) |
| order | o | rating_desc | global popularity, default |
| | | user_rating_desc | for the coverlogged user, best reviews |
| | | rating_week_desc | |
| | | release_date_desc | |
| | | date_desc | |
| | order (diff ??) | rating_week_desc | |
| | item_o (diff ??) | track_no_asc | |
| | | random | |
| number | n | //value// | number of item to get back |
| Album info | ali | min (default) | id |
| | | info_min | //add to previous// name, artist_id, archive_set |
| | | info_common | //add to previous// lengths, release_date, public_date, class, com_level, buyurl, filename, imagenum, status, mod, license_id, license_music_multiple, license_artwork_id, review_num, review_note, review_num_week, review_note_week, public_date_f, release_date_f, length_total |
| | | full | //add to previous// genre_str, genre_str_lang, desc_str, desc_str_lang, referrer_count, playlisted_count, lowfi_count, favourited_count, tracker_seeds_num, tracker_clients_num, tracker_finished_num, upload_date, validation_date, relance_date, id3genre, validation_url, root_audio, root_images, root_torrents, images{}, desc_html, archives{}, certif{} |
| | | desc | description |
| | | images | //Don't work// |
| | | archives | link to download |
| | | tracker | status of tracker (use with aenc) |
| | | genre | tags |
| Artist info | ari | min (default) | id |
| | | info_min | //add to previous// name, dispname |
| | | info_common | //add to previous// homepage, date_start, date_join, date_end, image |
| | | full | //add to previous// genre_str, genre_str_lang, desc_str, desc_str_lang, creator_user_id, forum_id, pays, departement, ville, desc_html, geo_countryname, geo_str1, relationjam{} |
| | | desc | //add// desc_str, desc_str_lang, desc_html |
| | | geo | //add// pays, departement, ville, id, geo_countryname, geo_str1 |
| Playlist info | pli | //any// (default) | name, id, public, user_id, albumcount |
| Review info | rri | min (default) | id |
| | | info_min | //add to previous// title, album_id, user_id, note1, agree_cnt, pubdate, pubdate_f, review_link |
| | | info_common | //add to previous// lang, reply_topic_id, reply_topic_lang, blog_id, blog_link, blog_exclusive, reply_link, num_replies |
| | | full | //add to previous// review_text, date |
| User info | uri | min (default) | id |
| | | info_min,info_common | //add to previous// name, profile_link |
| | | full | //add to previous// avatar, pays, departement, has_transperm, inscr_date, avatarurl, classes{}, classes_html |
| | | avatar | //add// avatar, avatarurl |
| Tag info | tgi | min (default) | id |
| | | info_common,full | //add to previous// name |
| Track info | tri | min (default) | id |
| | | info_min | //add to previous// album_id, name, track_no |
| | | info_common | //add to previous// lengths, filename, com_level, parental_level, license_id |
| | | full | //add to previous// lyrics_text, lyrics_exists, lyrics_lang, lyrics_mod_date, id3genre, length |
| User id | uid | //value// | Select info related to an album/track. TODO artist images. It adds the secondaryParameters "artwork_size" and "artwork_id".user |
| Stream encoding | aue (audio enc) | ogg1, ogg2, mp31 | lowfi OGG (q-1), lowfi OGG q4, lowfi MP3 (96kbits) (default for streaming / player) |
| P2P | p2pnet | torrent (default), ed2k | use with target p2p |
| | aenc,are (archive enc : tracker | ogg3, mp32 | hifi OGG q7, hifi MP3 (200kbits+) |
| Artwork | artwork_size | //value// | 70,100,130,200,300,400, etc (mail us for get a custon one) |
| | artwork_id | //value// | |
| show / hide | item_showhidden | 1, 2, //other// (default) | all albums, albums.status<>'V', albums.status='V' |
| | shownotmod | 1, 2, //other// (default) | all albums, albums.`mod`=0, albums.`mod`=1 |
| | item_nid | $previous_ids | |
| SubSettings | subset | user_star | |
| | item_subset | user_notign, user_notlater, user_star | |
| Others | item_program | 13 | artist_revenueshare |
| | json_iddict | 1 | change Json format from [{"id":1234}] to {"1234":{"id":1234}} (example of result) |
| | item_nids | $previous_ids | |
| | displangs | $rl | |
"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.=== More Examples ===
== TARGET = "data" ==| **Description** | **Url example** |
| 5 latest ablums released (minimal information) | http://www.jamendo.com/get/album/list/album/data/json/?n=5&o=release_date_desc&ali=info_min |
| All album info and common artist info of the first album released | http://www.jamendo.com/get/album/list/album/data/json/?n=1&o=release_date_asc&ali=full&ari=info_common |
| Ids of album by "both" artist | http://www.jamendo.com/get/album/list/artist/data/json/?names=both |
| Tags of album which id is 33 | http://www.jamendo.com/get/tag/list/album/data/json/?ids=33&tgi=info_common |
| Complete user info | http://www.jamendo.com/get/user/list/user/data/json/?names=sylvinus&uri=full |
todo== Others ==
== FORMAT = "play" ===== Other Loadertypes ===
This one is an alias for the default playlist format of the currently logged user. It defaults to "m3u". It is widelyThese Loadertypes are still used on Jamendo.Jamendo portal and [[JamendoApps]]. They are a bit shorter to write.
== Data Model ==There is a description of used URL on Jamendo portal :
{{{| **Description** | **Url example** |
| Get //item// from **name** of other //item// | **name** loadertype |
| album id from artist (name) | http://www.jamendo.com/get/album/name/artist/id/json/both/?n=all&item_program=&album_shownotmod=1&album_showhidden=1 |
| artist id | http://www.jamendo.com/get/artist/name/artist/id/json/both/ |
| //parameters// | http://www.jamendo.com/get/artist/name/artist/id/json/both/?n=all&item_shownotmod=1&item_showhidden=1 |
| restrict geo area | http://www.jamendo.com/get/artist/name/artist/id/json/both/?geo=all |
| track id from artist | http://www.jamendo.com/get/track/name/artist-album/id/json/both/ |
| //parameters// | http://www.jamendo.com/get/track/name/artist-album/id/json/both/?n=all&item_program=&album_shownotmod=1&album_showhidden=1 |
| artist info | http://www.jamendo.com/get/artist/name/artist/data/json/both/?ali=&ari=full&tri= |
| albums info from artist name | http://www.jamendo.com/get/album/name/artist/multi/json/both/?targets=id+desc2&n=all&album_shownotmod=1&album_showhidden=1 |
| Get //item// from **id** of other //item// | **id** loadertype |
| user name (from his id) | http://www.jamendo.com/fr/get/user/id/user/name/plain/2 |
| tag name | http://www.jamendo.com/get/tag/id/tag/name/plain/23 |
| tag name from album | http://www.jamendo.com/get/tag/id/album/name/json/33?item_o=weight_desc&n=5 |
| album id from artist (id) | http://www.jamendo.com/get/album/id/artist/id/json/5/?item_program=13&item_shownotmod=0&item_showhidden=0 |
| album from tag (error rating!) | http://www.jamendo.com/get/album/id/tag/id/json/23?o=rating_desc&countall=1 |
| albums info from album | http://www.jamendo.com/get/album/id/album/data/json/33?ali=info_common&ari=info_common |
| artist(param) and album infos | http://www.jamendo.com/get/album/id/album/data/json/33/?ali=full+object&ari=full+object&tri= |
| tracker info (for specified enc) | http://www.jamendo.com/get/album/id/album/data/json/33?ali=info_min+archives+tracker&ari=info_min&aenc=ogg3 |
| albums info from artist | http://www.jamendo.com/get/album/id/artist/data/json/5/?ali=info_min&n=all |
| //parameters// | http://www.jamendo.com/get/album/id/artist/data/json/5?ali=full&ari=full+object&item_showhidden=1&item_shownotmod=1 |
| artist info (description) | http://www.jamendo.com/get/artist/id/artist/data/json/5?ari=desc+info_common |
| news info from user | http://www.jamendo.com/get/news/id/user/data/json/2?nwi=info_common&n=50&item_o=id_desc&item_showmailed=1&item_showviewed=1 |
| playlist info | http://www.jamendo.com/get/playlist/id/playlist/data/json/?pli=full&uri=info_min |
| review info | http://www.jamendo.com/get/review/id/review/data/json/4844?rri=full&class=review&displangs=current&o=date_desc |
| | http://www.jamendo.com/get/ringtone/id/ringtone/data/json/?rgi=file |
| tag info | http://www.jamendo.com/get/tag/id/tag/data/json/23?tgi=full |
| track info from album | http://www.jamendo.com/get/track/id/album/data/json/33?ali=full&ari=full+object&tri=full&item_o=track_no_asc&showhidden=1&shownotmod=1 |
| //parameters// | http://www.jamendo.com/get/track/id/album/data/json/33?ali=full&ari=info_common&tri=info_common |
| track info from playlist | http://www.jamendo.com/get/track/id/playlist/data/json/4681/?n=all&tri=info_min |
| user info | http://www.jamendo.com/get/user/id/user/data/json/2?uri=info_min+avatar |
| « Album : review title » | http://www.jamendo.com/get/review/id/review/desc2/json/4844?ali=info_common+images&rri=full |
| | http://www.jamendo.com/get/track/id/track/datasmall/json/1234/?json_iddict=1 |
One to One=== FIXME : ------
One to Many : -----*
Many to Many : *----* remove ===
Concert *-----* Artist *-----* User
|
|
* What association can be done ?
Review *----* Album *------* Tag *-------* User
*
| | *
User | |
| |
* *
License ------* Track *------* Playlist *-------UserCaption :
* **A/A/T** : Something of album, artist, track
* **** page, tag, //etc//.
}}}| **Meaning** | / [itemUnit] | / [loadtype] | / [parametersUnit] | / [targetName] | / [formatName] | ?[parameters] |
| Title of //**A/A/T**// of artist named //sbdy// | //**A/A/T**// | list | artist | title | plain | name=//sbdy// |
| Page of //**A/A/T**// of artist named //sbdy// | //**A/A/T**// | list | artist | page | plain | name=//sbdy// |
| Title of //**A/A/T**// identified with //**A/A/T**2//'s //id// | //**A/A/T**// | list | //**A/A/T**2// | title | plain | ids=//id// |
| Tags name of //**A/A/T**// identified with his //id// | tag | list | //**A/A/T**// | name | plain | ids=//id// |
| Ids of //**A/A/T**// | //**A/A/T**// | list | //same as first **A/A/T**// | id | plain | //other options// |
| RSS field | album | list | album | page | rss2 | //other options// |