MusicBrainz API/XML

From MusicBrainz Wiki
< MusicBrainz API
Revision as of 06:02, 5 May 2010 by Murdos (talk | contribs) (inc=)

XML Web Service v2

This is my proposal on how V2 of the XML_Web_Service should work. --warp.


We have six resources on our web service which represent core entities in our database:

 artist, label, recording, release, release-group, work

We also provide a web service interface for the following non-core resources:

 rating, tag, collection

On each entity resource, you can perform three different GET requests:

 lookup:   /<ENTITY>/<MBID>?inc=<INC>
 browse:   /<ENTITY>?<ENTITY>=<MBID>&limit=<LIMIT>&offset=<OFFSET>&inc=<INC>
 search:   /<ENTITY>?query=<QUERY>&limit=<LIMIT>&offset=<OFFSET>

Of these:

  • Lookups and Browse requests are documented in following sections.
  • Searches are implemented by the search server and are not currently documented here, suffice to say that <QUERY> uses the advanced query syntax understood by lucene. This is documented for the current server at .
  • ratings, tags and collections are not currently documented for /ws/2.
〜 Do we have any documentation on /ws/2 searches? Either full docs or changes from the page linked above?. --warp.


You can perform a lookup of an entity when you have the MBID for that entity:

 lookup:   /<ENTITY>/<MBID>?inc=<INC>


The inc= is parameter allows you to request more information to be included about the entity. Any of the entities directly linked to the entity can be included.

 /ws/2/artist            recordings, releases, release-groups, works
 /ws/2/label             releases
 /ws/2/release-group     artist, releases
 /ws/2/work              artist
 /ws/2/recording         artist, releases
 /ws/2/release           artist, label, recordings, release-groups

All lookups which include releases allow a seperate status= argument to further narrow down the type of releases you are looking for. All lookups which include release-groups allow a type= argument to narrow down the release-groups.

Note that the number of linked entities returned is always limited to 25, if you need the remaining results, you will have to perform a browse request.

inc= arguments which affect subqueries

Some additional inc= parameters are supported to specify how much of the data about the linked entities should be included:

 - discids           include discids for all media in the releases
 - media             include media for all releases, this includes the # of tracks on each medium.
 - puids             include puids for all recordings
 - isrcs             include isrcs for all recordings
 - iswcs             include iswcs for all works
 - various-artists   include only those releases on which the artist appears on one of the tracks, 
                     but not in the artist credit for the release itself (this is only valid on a
                     /ws/2/artist?inc=releases request).
〜 ISWC should IMO always be provided for works, and thus not require a inc=iswcs. Indeed it is just a property of a work, like e.g. the country of an artist. --murdos.

As a special case, artists will be included for recordings on a /ws/2/release?inc=artist+recordings lookup.

To get all ISWCs for ABBA for example, you could do:


(Just using 'inc=iswcs' would not return any iswcs, you need to include works to use 'iswcs').

Misc inc= arguments

 - aliases           include artist, label or work aliases


inc= arguments to include relationships work exactly like they do in /ws/1:

 - artist-rels
 - label-rels
 - recording-rels
 - release-rels
 - release-group-rels
 - url-rels
 - work-rels


Browse requests are a direct lookup of all the entities directly linked to another entity. (with directly linked I am referring to any relationship inherent in the database, so no ARs). For example, you may want to see all releases on netlabel ubiktune:


Note that browse requests are not searches, in order to browse all the releases on the ubiktune label you will need to know the MBID of ubiktune.

Linked entities

The following list shows which linked entities you can use in a browse request:

 /ws/2/artist            recording, release, release-group, work
 /ws/2/label             release
 /ws/2/release-group     artist, release
 /ws/2/work              artist
 /ws/2/recording         artist, release
 /ws/2/release           artist, label, recording, release-group

As a special case, release also allows track_artist, which is intended to allow you to browse various artist appearances for an artist. It will return any release where the artist appears in the artist_credit for a track, but NOT in the artist_credit for the entire release (as those would already have been returned in a request with artist=<MBID>).

〜 I think track_artist as described above is important, otherwise you will get client software requesting all recordings for an artist, followed by release requests for each of the recordings found earlier. --warp.

Release-groups can be filtered on type, and releases can be filtered on type and/or status. For example, if you want all the Live Bootleg releases by Metallica:


Or all albums and EPs by Autechre:


Note that filtering is mandatory, if you don't specify type or status the release and release-group resources will not return any results.


Browse requests are the only requests which support paging, any browse request supports an 'offset=' argument to get more results. Browse requests also support 'limit=', the default limit is 25, and you can increase that up to 100.


Just like with normal lookup requests, the server can be instructed to include more data about the entity using an 'inc=' argument. Supported values for inc= are:

 /ws/2/artist            aliases
 /ws/2/label             aliases
 /ws/2/release-group     artist
 /ws/2/work              artist, aliases
 /ws/2/recording         artist
 /ws/2/release           artist, label
〜 murdos added work aliases here, but I don't see these in the database, what am I missing? --warp.
〜 warp should update his database. He is missing this code in master (code review, jira ticket) --murdos.

In addition to the inc= values listed above, all entities (except release) support:

 tags, ratings, user-tags, user-ratings
〜 we probably want to allow a few more inc= arguments here, though we can always add more later. --warp.