Jamendo Api Documentation

Jamendo Api Introduction

Rest-like API

Every Jamendo Api method is generically expressed as an entity or entity+subentity. The generic GET url form is the following: http[s]://api.jamendo.com/<version>/<entity>/<subentity>/?<api_parameter>=<value> As some of the RESTfull specifications (like the CRUD actions 1-1 mapping through HTTP methods, or the entity id received as get parameter) are not implemented in our framework, we rather prefer to define our API as RESTlike.

Http[s] methods

Read methods need an http or https GET method, while write methods need a POST. Note that you can always use SSL to improve your application security, and you have to use it in certain parts of the OAuth process.

Document format

Every api call returns a response document in the requested format: json, jsonpretty, xml. Such a response document (with a slightly different structure depending on the used format), will always contain some headers, and the results requested by your api call.
On every read method's documentation page and write method's documentation page you can see an example of a request and the corresponding response document.

Old (deprecated) Api

Old versions of the Jamendo Api, the 'get' and 'get2' versions, are deprecated, but for the moment still available through the api.jamendo/get2/* and api.jamendo/get/* urls. Those api will be working still for 1 year at least, but the returned data are not always granted to be up to date. For instance, data like playlists are already to be considered as 'frozen': if you add a playlist, you won't be able to read it with 'get' and 'get2' api.
Some documentation can still be found in the old Jamendo developer wiki.

The get2 api set up, provided the possibility of downloading an XML dump of the Jamendo database, containing the list of artists, albums and tracks with their tags. Such service may or may not be stopped next year, depending on the Jamendo dev community usage and feedbacks.

Need an help?

If you have any question, suggestion, bug or malfunction to report, write us and actively partecipate to the Jamendo GoogleGroup! Someone of our team or of the developer community itself will answer you as soon as possible.

Basic authentication

Every api call needs the 'client_id' GET parameter. To get your client_id, you have to sign up for a developer account on our Developer Portal. Note that for some api methods (to read/write a Jamendo user's private data), in addition to the 'client_id', you will need to implement an OAuth2 authentication workflow.

Obtain a 'client_id'

With your new developer account, you will be able to create 'applications'. For each application you will get a private 'client_id' that you can use to authenticate all API queries made by your application. If you want to make some quick tests, you can use this client id: b6747d04 (ONLY for TESTING the read api).

Choose your plan

By default, all 'applications' created in your account have the 'read only' plan applied (it allows you to use all the read api methods). If you need to use our write api, you have to change the plan of your application to the 'Read & Write' plan. This change requires approval by the Jamendo team, so don't forget to complete your application description correctly before applying for read access (application name, description, usage, ...).

Statistics and alerts

With your account you will also have a access to the usage statistics of your application(s), that you can use to monitor how and how many users are using your application. Note that if your application overpass the limit of 500 000 hits per month, you will receive a simple email alert, and a warning in each api header. Don't panic, you can keep using our Api even over a million calls per month without any risk, but please try to optimize your code to prevent wasting resources, for example by caching responses instead of making a new request each time.

Jamendo Api Read Methods

As mentioned in the introduction, all read api methods need have to be http or https GET requests. You can find the list of all existing read methods below, linking to their respective documentation page.

List of Read Methods

Parameters

Every Read Method (the base url) accepts a given list of get parameters, with some conditions imposed on their values (type, accepted values, can it have multiple values, etc). If one ore more of these conditions are not respected, the api framework will raise an appropriate error code and message, while any get parameter not belonging to the accepted list will simply get ignored, it will raise a warning though.

Every method's documentation page presents a table, containing the list of accepted parameters, their value type and a description. In the type-column, the syntax []integer means that such parameter also accepts multiple values, and each of those values must be an integer. In this case, multiple values can be specified using ' ' (a space) or '+' (a plus sign) as separator. A maximum number of accepted multiple values exists, and it's 50.
Note that also the enum type exists.

By default every /entity/subentity method will inherit the parameters declaration of its relative /entity "parent" method. In addition to this, almost every read method accepts and shares the declaration of the following common parameters. Any eventual exception to this rule is clearly marked on the method documentation pages.

nametypedescriptionrequired
client_idstringA Client Id provided by devportal.jamendo.com. For ONLY testing purpose you can use the following client_id: b6747d04yes
formatenum: {xml, json, jsonpretty}The results formatting typeno
callbackstringUse this parameter to have the response json wrapped in a callback function (jsonp technique). Such feature is enable only for json format and GET requests; if used in combination with other formats or a not-get request, the callback parameter is simply ignored and a warning is raisedno
offsetintegerThe position to start returning results fromno
limitstringThe max number of results to return. Default is 10 and Max is 200. Using the keyword 'all' still a max of 200 rows will be returnedno
order[]enum: {}Sort results by the queried field(s).
You can specify whether to follow an ascending or descending order adding the suffix _asc or _desc to every field (order=field_asc). Asc is the default one.
no

Returned fields

Every method will return a list of entities matching your query. Every entity is described by a list of fields (and their values of course) that does not forcedly have a correspondent parameter, although it often is the case. Note that at the moment the returned fields are statically returned, meaning that you cannot "switch off" or "switch on" any returned field.

Entities aggregation

You'll notice that methods like /playlists/tracks lists the 'track' subentities in an aggregated and not tabular way. In this case the limit paramter still refers to the number of playlists to return, and not the number of tracks-per-playlist.
Soon we will enable the subentities limit and offset handling through parameters in the form of <subentity>_limit and <subentity>_offset. For instance, in the method /playlists/tracks, the parameter tracks_limit will set the limit of tracks per playlist.
Be carefull because there's a maximum limit of total aggregated subentities returned by entity/subentity methods and thus we cannot ensure that the number of returned subentities corresponds to the expected amount. Such limit is 400, while the maximum number of entities returned is 200.

Jamendo API Write Methods

As mentioned in the introduction, all write API methods need to use an http or https POST request.
If you need to use our write api, you have to change the plan of your application to the 'Read & Write' plan in your developer account. This change requires approval by the Jamendo team, so don't forget to complete your application description correctly before applying for read access (application name, description, usage, ...).
As for read methods a response document is always returned. Such a document always contains the headers with status, code and messages and just eventually also contains a specific return value (as the id of the playlist you have created through /setuser/playlist/).
Note that all write methods need the user to be logged in and therefore your application needs to implement an OAuth2 client to communicate with our OAuth2 server.

List of Write Methods

Jamendo Api Response Codes

Every call returns a document containing headers and results. The headers are composed of four fields:

  • status: it can be either 'succeed' or 'failed'
  • code: will be 0 in case of a success or an error Id (different then zero) in case of a fail. All the information you need is in the table below.
  • error_message: contains the error message if an error occured else it is empty. Every error message will contain the type of the error (see in table below) as well as the contextual error description
  • warnings: may contain warning messages if any. Warnings get raised, but do not let the request fail.


codetypedescription
0SuccessSuccess (or success with warning)
1ExceptionA generic not well identificated error occurred
2Http MethodThe received http method is not supported for this method
3TypeOne of the received parameters has a value not respecting requirements such as type, range, format, etc
4Required ParameterA required parameter has not been received, or it was empty
5Invalid Client IdThe client Id received does not exists or cannot be validated
6Rate Limit ExceededThis requester app or the requester IP have exceeded the permitted rate limit
7Method Not FoundJamendo Api rest-like reading methods are in the format api.jamendo.com/version/entity/subentity (subentity is optional). This exception is raised when entity and/or subentity methods don't exist
8Needed ParameterA needed parameter has not been received or/and this needed parameter has not the needed value
9FormatThis exception is raised when the api call requests an unkown output format
10Entry PointThe used IP and/or port is not recognized as valid entry point
11Suspended ApplicationThe client application has been suspended (illegal usage, ...)
12Access TokenInvalid Access Token.
13Insufficient ScopeInsufficient scope. The request requires higher privileges than provided by the access token
API powered by 3scale API Management solution