== Purpose ==
This powerful API allows you to fetch any data related to the music on jamendo. It is read-only.
Things you can query with this API : albums, artists, tracks, users, tags, playlists, reviews, ...
* Pattern of URL to use
{{{www.jamendo.com/get2/[targets]/[unit]/[format]/<relations>/<?param><¶m>...}}}
| **Parameter** | **Description** | **Values** |
| target | element of the unit you want to get | id, name, image, url... |
| unit | unit you want to get | album, artist, track... |
| format | format of returned data | plain text, php array, ... |
| relations | relations between units you specified | artist_album, album_track,... |
| param | global parameters or unit-specific parameters | number of result, order params, ... |
== What are Targets and Units ==
=== Introduction ===
Targets and units are deeply linked together. They are used to DESCRIBE the data you are asking for.
\\
In the URL, you will ask for the TARGETS of a UNIT, like "ID of an ALBUM", or "NAME of an ARTIST".
\\
In these simple examples, targets are "id" and "name", and units are "album" and "artist". The urls of such examples look like:
www.jamendo.com/get2/id/album/...
www.jamendo.com/get2/name/artist/...
\\
\\
To sum up, units are the main elements you ask for (album, artist, playlist, track...), and targets (id, name, ...) are part of units.
=== How to get several targets ? ===
You may need several informations about a unit. Then, you can specify several targets using the plus (+) symbol :
If you need the id and the name of an album, use : www.jamendo.com/get2/id+name/album/...
The pattern of such urls is : www.jamendo.com/get2/[target]+[target]<+target...>/[unit]/...
=== How to get several targets from several units ? ===
You may need several informations about several units.
As it's not possible for Musiclist2 to guess how are related the units you ask for, you have to specify relations between them.
As 2 units may be related in several ways, it allows you to give the specific relation you want to use.
\\
If you need the id and the name of an album, and the name of its artist, you have to use the relation "album_artist"
www.jamendo.com/get2/id+name+artist_name/album/plain/album_artist/
"album_artist" is a simple relation that links an artist to its albums.
The classic pattern of such urls is : www.jamendo.com/get2/[unit1_target]+[unit1_target]+[unit2_target]<+unit2_target>/[unit1]/[format]/[relation between unit1 and unit2]
Refer to the section "relations" for more informations about how to get informations about several units.
=== Special target ===
You may need to know how many results your query should return. for this, you can use the target "totalcount".
example :
number of albums in jamendo : http://www.jamendo.com/fr/get2/totalcount/album/jsonpretty
== Parameters ==
Parameters allows you to specify condition in your requests, order the data, limit the number of result...
=== How to specify conditions ? ===
You can specify condition on your queries using units and targets.
If you've specified just one unit, you can use targets of this unit to give them expected values.
Example : you want the name of the album which id is 33 :
http://www.jamendo.com/get2/name/album/jsonpretty/?id=33
If you've specified relations, ie if you are working on several units, you will have to specify parameters according to the main unit.
Example : you want the name of the artist which has an album with id 33 :
http://www.jamendo.com/get2/name/artist/jsonpretty/artist_album/?album_id=33
=== How to order the data ? ===
You can order your data by one or several parameters. Each unit has its own specific order parameters, and Musiclist2 provides global order parameters.
The classic pattern of urls with order params are : www.jamendo.com/get2/[targets]/[unit]/[format]/<relations>/?order=<param1>_<asc/desc>+<param2>_<asc/desc>
\\
\\
* **Parameters used**
Parameters used to order can be either targets, unit specific parameters, or global order params provided by Musiclist2.
For more informations about the targets used as order parameters, and unit specific parameters, report to the section "complete units reference"
\\
For more informations about the global order params provided by Musiclist2, refer to the section "Global order params"
\\
\\
* **Order modes**
Asc and Desc are modes of order. it allows you to order in ASCendant mode or in DESCendant mode.
If you don't specify asc or desc param, Musiclist2 will order in ASC by default.
\\
\\
* **Can i order by several parameters ?**
Yes, you just have to specify several parameters, using the plus (+) symbol.
=== How to limit results ? ===
You can limit the number of rows in you results using the parameter "n". By default, the number of rows is limited to 20.\\
to get X rows, just add the parameter "?n=X"\\
to get all rows, add the parameter "?n=all"
Examples :
Get the 3 first tracks of album 33 :
www.jamendo.com/get2/name+id/track/jsonpretty/album_track/?album_id=33&n=3
Get all tracks of album 33 :
www.jamendo.com/get2/name+id/track/jsonpretty/album_track/?album_id=33&n=all
== Formats ==
Formats are the way data are sent to you. there are several formats :
json, jsonpretty (easy-to-read JSON), m3u, plain (text)
== Relations ==
Relations are used to specify several units on which you need informations.
Example : you need the name and the id of an album, and the id of its artist.
then, url looks like :
www.jamendo.com/get2/id+name+artist_id/album/plain/artist_album
The main unit is album, and we ask for his targets "id" and "name".
we also ask for the target "artist_id", which is handled like "the target 'id' of the unit 'artist'".
we get the specific artist id of the album with the relation "artist_album"
** NOTE ** : all relations are **SYMETRIC**, which means that you can use both "artist_album" and "album_artist", it will return the same result.
Here are the complete list of relations of units :
=== Artist ===
|**relation name**|**Description**|**examples**
| album_artist | "albums of this artist" | http://www.jamendo.com/get2/name+id/album/plain/album_artist/?artist_idstr=both
| artist_tag | "tags of an artist" | http://www.jamendo.com/get2/name+weight/tag/plain/artist_tag/?artist_idstr=both
| artist_user_starred | "users who starred this artist" | http://www.jamendo.com/get2/idstr/user/plain/artist_user_starred/?artist_idstr=both
=== Album ===
|**relation name**|**Description**|**examples**
| album_artist | "artist of an album" | http://www.jamendo.com/get2/name+id/artist/plain/album_artist/?album_id=33
| album_license | "License of an album" | http://www.jamendo.com/get2/url+id/license/jsonpretty/album_license/?album_id=33
| album_review | "reviews of an album" | http://www.jamendo.com/get2/text+id/review/jsonpretty/album_review/?album_id=33
| album_tag | "tags of this albums" | http://www.jamendo.com/get2/name+weight/tag/plain/album_tag/?album_id=33
| album_track | "tracks of this album" | http://www.jamendo.com/get2/name+id/track/plain/album_track/?album_id=33
| album_user_starred | "users who starred an album" | http://www.jamendo.com/get2/idstr/user/plain/album_user_starred/?album_id=33
=== Playlist ===
|**relation name**|**Description**|**examples**
| playlist_review | "reviews of a playlist" | http://www.jamendo.com/get2/text+id/review/jsonpretty/playlist_review/?playlist_id=32582
| playlist_track| "tracks of this playlist" | http://www.jamendo.com/get2/name/track/jsonpretty/playlist_track/?playlist_id=32582
| playlist_user | "user with this playlist" | http://www.jamendo.com/get2/idstr/user/jsonpretty/playlist_user/?playlist_id=32582
| playlist_user_starred | "user who starred this playlist" | http://www.jamendo.com/get2/idstr/user/jsonpretty/playlist_user_starred/?playlist_id=32582
=== Track ===
|**relation name**|**Description**|**examples**
| tag_track | "tags of this track" | http://www.jamendo.com/get2/name+weight/tag/jsonpretty/tag_track/?track_id=285
| license_track | "license of this track" | http://www.jamendo.com/get2/url+id/license/jsonpretty/license_track/?track_id=285
| review_track | "reviews of this track" | http://www.jamendo.com/get2/text+id/review/jsonpretty/review_track/?track_id=285
| album_track | "album of this track" | http://www.jamendo.com/get2/name+id/album/jsonpretty/album_track/?track_id=243
| playlist_track| "playlists with this track" | http://www.jamendo.com/get2/name+url/playlist/plain/playlist_track/?track_id=243
=== Tag ===
|**relation name**|**Description**|**examples**
| tag_user_starred| "users who starred this album" | http://www.jamendo.com/get2/idstr/user/plain/tag_user_starred/?tag_idstr=hardcore
| artist_tag | "artist with this tag" | http://www.jamendo.com/get2/name+url/artist/plain/artist_tag/?tag_idstr=metal
| album_tag | "albums with this tag" | http://www.jamendo.com/get2/name+url/album/plain/album_tag/?tag_idstr=rock
| track_tag | "tracks with this tag" | http://www.jamendo.com/get2/name/track/plain/track_tag/?tag_idstr=jazz
=== Review ===
|**relation name**|**Description**|**examples**
| review_user| "user who wrote this review" | http://www.jamendo.com/get2/idstr/user/plain/review_user/?review_id=59231
| review_user_agree| "user who agreed with this review" | http://www.jamendo.com/get2/idstr/user/plain/review_user_agree/?review_id=26801
| album_review | "album of this review" | http://www.jamendo.com/get2/name+url/album/plain/review_album/?review_id=26801
| playlist_review | "playlist of this review" |
| review_track | "track of this review" |
=== License ===
|**relation name**|**Description**|**examples**
| album_license | "albums with this license" | http://www.jamendo.com/get2/name+url/album/jsonpretty/album_license/?license_id=4
| license_track | "tracks with this license" | http://www.jamendo.com/get2/name/track/jsonpretty/track_license/?license_id=4
=== User ===
|**relation name**|**Description**|**examples**
| artist_user_starred | "artists this user starred" | http://www.jamendo.com/get2/name/artist/plain/artist_user_starred/?user_idstr=pierrotsmnrd
| album_user_starred | "albums this user starred" | http://www.jamendo.com/get2/name+url/album/plain/album_user_starred/?user_idstr=pierrotsmnrd
| playlist_user_starred | "playlists this user starred" | http://www.jamendo.com/get2/name+url/playlist/plain/playlist_user_starred/?user_idstr=pierrotsmnrd
| playlist_user | "playlists of this user" | http://www.jamendo.com/get2/name+url/playlist/plain/playlist_user/?user_idstr=pierrotsmnrd
| tag_user_starred| "tags this user starred" | http://www.jamendo.com/get2/name+url/tag/plain/tag_user_starred/?user_idstr=pierrotsmnrd
| review_user_agree| "reviews this user agreed with" | http://www.jamendo.com/get2/text+id/review/plain/review_user_agree/?user_idstr=pierrotsmnrd
| review_user| "reviews this user wrote" | http://www.jamendo.com/get2/text+id/review/plain/review_user/?user_idstr=pierrotsmnrd
== Complete list of units with their targets, filter parameters and order parameters ==
=== **unit artist** ===
| **targets** | **description** | **examples** |
| id | numeric id of the artist | Both : 5, Madame Olga : 2464
| idstr | string id of the artist | Both : both, Madame Olga : madameolga
| name | Display name of the artist. different of idstr | "Both", "Madame Olga"
| image | link to the image of the artist | Both : {{{http://img.jamendo.com/artists/b/both.jpg}}}, Madame Olga : {{{http://img.jamendo.com/artists/m/madameolga.jpg}}}
| url | link to the page of the artist on Jamendo | Both : {{{http://www.jamendo.com/artist/both}}}
| mbgid | String id of the artist on MusicBrainz | Both : {{{0781a3f3-645c-45d1-a84f-76b4e4decf6d}}}
| mbid | Integer id of the artist on MusicBrainz | Both : 263632
| genre | Description of the artist (written by the artist) | "Both" : "Eclectick Rock", "Madame Olga" : "Fusion-Rock-Electro"
| **params** | **description** | **examples** |
| id | id of the artist | ?id=5
| idstr | string id of the artist | ?idstr=both
| mbid | Integer id of the artist on MusicBrainz | ?mbid=263632
| mbgid | String id of the artist on MusicBrainz | ?mbgid={{{0781a3f3-645c-45d1-a84f-76b4e4decf6d}}}
| hasalbums | only get the artists with albums on Jamendo | ?hasalbums=1
| hasmbid | only get the artists with a musicbrainz id | ?hasmbid=1
| fuzzynamesearch | allows you to search for artists with a part of their name | ?fuzzynamesearch=madame
| fuzzycitysearch | allows you to search for artists from a city | ?fuzzycitysearch=paris
----
=== **unit album** ===
| **targets** | **description** | **examples** |
| id | numeric id of the album | "Simple Exercice" : 33
| name | name of the album | "Simple Exercice"
| image | link to the cover of the album | "Simple Exercice" : {{{http://img.jamendo.com/albums/33/covers/1.100.jpg}}}
| url | link to the page of the album on Jamendo | "Simple Exercice" : {{{http://www.jamendo.com/album/33}}}
| duration | Total length of the album (in seconds) | "Simple Exercice" : 1586 (seconds)
| genre | Description of the album (written by the artist) | "Simple Exercice" : "Rock éclectique"
| **params** | **description** | **examples** |
| idstr | string id of the artist | ?idstr=both
| mbid | Integer id of the album on MusicBrainz | ?mbid=375887
| mbgid | String id of the album on MusicBrainz | ?mbgid={{{602ede40-fcbc-4142-94b5-f72204bba21f}}}
| type | either short or long albums (a short album lasts less than 20 minutes) | ?type=long or ?type=short
▼