History:Development/XML Web Service/Version 1: Difference between revisions

From MusicBrainz Wiki
Jump to navigationJump to search
(Added a couple of examples from Kevin McGrail (Imported from MoinMoin))
 
(103 intermediate revisions by 23 users not shown)
Line 1: Line 1:
{{Status|This web service is no longer in service! The current XML web service implementation [[XML_Web_Service|is documented here]].}}
[[Image:Attention.png]] '''Status:''' ''Beta testing in progress. Please do not change unless you are told to!''


<small>[[Products]] > XML Web Service Version 1 </small>

----


=Introduction=
=Introduction=


Line 15: Line 11:
=The MusicBrainz Metadata Model=
=The MusicBrainz Metadata Model=


[[MusicBrainz]] uses an object oriented schema to model music metadata. The main classes are artist, release and track, each with a different set of attributes and relations. Apart from their traditional relations (artists have releases, releases contain tracks), a more powerful schema was introduced (sometimes called [[Advanced Relationships|AdvancedRelationships]]).
[[MusicBrainz]] uses an object oriented schema to model music metadata. The main classes are artist, release, track and label, each with a different set of attributes and relations. Apart from their traditional relations (artists have releases, releases contain tracks), a more powerful schema was introduced (sometimes called [[Advanced Relationships|AdvancedRelationships]]).


It allows users to link an object of one class to an object of any other class (URLs are permitted, too). Many different link types exist (see [[Advanced Relationship Type|AdvancedRelationshipType]] for a list), which can be used to specify the artist who did background vocals on a release or track, who is married to whom, where an artist's offical homepage is, and a lot more. Those links themselves may have attributes, with their semantics depending on the link type.
It allows users to link an object of one class to an object of any other class (URLs are permitted, too). Many different link types exist (see [[Advanced Relationship Type|AdvancedRelationshipType]] for a list), which can be used to specify the artist who did background vocals on a release or track, who is married to whom, where an artist's offical homepage is, and a lot more. Those links themselves may have attributes, with their semantics depending on the link type.
Line 23: Line 19:
==The Artist Class==
==The Artist Class==


In [[MusicBrainz]], [[Artist|artists]] always have a unique ID, a [[Artist Name|name]] and a [[Sortname|SortName]]. If the artist name isn't unique, a ''disambiguation'' comment is used to provide more information about the artist (see [[Identically Named Artists|IdenticallyNamedArtists]]). Additionally, an artist may also be flagged as ''Person'' or ''Group'' and it can have a ''begin date'' and an ''end date''. For persons, these are the dates of birth and death, for groups they are the founding and dissolving dates.
In [[MusicBrainz]], [[Artist|artists]] always have a unique ID, a name and a sort name. If the artist name isn't unique, a ''disambiguation'' comment is used to provide more information about the artist. Additionally, an artist may also be flagged as ''Person'' or ''Group'' and it can have a ''begin date'' and an ''end date''. For persons, these are the dates of birth and death, for groups they are the founding and dissolving dates.


An artist can have any number of releases and relations to other artists, releases, tracks and URLs.
An artist can have any number of releases and relations to other artists, releases, tracks and URLs.

==The Release Group Class==
A [[Release_Group|release group]] aggregates similar releases. All release groups have a unique ID, a title and one or more releases. Just like releases, release groups have a type ("Album", "Compilation", "Single" etc.).


==The Release Class==
==The Release Class==


All releases have a unique ID, a title and one or more tracks. Each release has a type ("Album", "Compilation", "Single" etc.), a status ("Official", "Promotion", "Bootleg") and [http://musicbrainz.org/wd/AlbumLanguage language information]. A release may also have additional release information, which are represented as a list of (''country'', ''date'') tuples, also called ''release events''.
All releases have a unique ID, a title and one or more tracks. Each release has a type ("Album", "Compilation", "Single" etc.), a status ("Official", "Promotion", "Bootleg") and [[Release Language|language information]]. A release may also have additional release events, which are represented as a list of (''country'', ''date'') tuples, sometimes called ''release information''.


A common use case is to look up a release using a [[Disc ID|DiscID]] generated from an Audio CD's table of contents (TOC). A release can have any number of DiscIDs (including none), mostly due to different pressings. In rare cases, where two different CDs have the same TOC, a DiscID may map to more than one release.
A common use case is to look up a release using a [[Disc ID|DiscID]] generated from an Audio CD's table of contents (TOC). A release can have any number of DiscIDs (including none), mostly due to different pressings. In rare cases, where two different CDs have the same TOC, a DiscID may map to more than one release.
Line 40: Line 39:


As with the other classes, a track object can have any number of relations to artists, releases, tracks and URLs.
As with the other classes, a track object can have any number of relations to artists, releases, tracks and URLs.

==The Label Class==

In [[MusicBrainz]], [[Label|labels]] always have a unique [[Label ID|ID]] and a name (they also used to have a sort name). If the label name isn't unique, a ''disambiguation'' [[Label Comment|comment]] is used to provide more information about the label. Additionally they may have a [[Label Code|code]], a [[Label Country|country]] and [[Label Begin Date|founding]] and [[Label End Date|dissolving]] dates. Each label has also a [[Label Type|type]] ("Distributor", "Holding", ...).

A label can have any number of releases and relations to other labels, artists, releases and URLs.


=The URL Schema=
=The URL Schema=


All [[MusicBrainz]] objects (artists, releases, tracks) are modeled as ''resources''. Resources have unique URLs and can be accessed using standard HTTP. Each resource is also part of a ''collection''. This is a special resource which represents all objects of a type.
All [[MusicBrainz]] objects (artists, release groups, releases, tracks and labels) are modeled as ''resources''. Resources have unique URLs and can be accessed using standard HTTP. Each resource is also part of a ''collection''. This is a special resource which represents all objects of a type.


For this version of the web service, the <code><nowiki>http://musicbrainz.org/ws/1/</nowiki></code> namespace has been reserved. It is further structured like this:
For this version of the web service, the <code><nowiki>http://musicbrainz.org/ws/1/</nowiki></code> namespace has been reserved. It is further structured like this:
Line 51: Line 56:
|-
|-
| <code><nowiki>http://musicbrainz.org/ws/1/artist/MBID</nowiki></code> || An individual artist
| <code><nowiki>http://musicbrainz.org/ws/1/artist/MBID</nowiki></code> || An individual artist
|-
| <code><nowiki>http://musicbrainz.org/ws/1/release-group/</nowiki></code> || Collection of all release groups
|-
| <code><nowiki>http://musicbrainz.org/ws/1/release-group/MBID</nowiki></code> || An individual release group
|-
|-
| <code><nowiki>http://musicbrainz.org/ws/1/release/</nowiki></code> || Collection of all releases
| <code><nowiki>http://musicbrainz.org/ws/1/release/</nowiki></code> || Collection of all releases
Line 59: Line 68:
|-
|-
| <code><nowiki>http://musicbrainz.org/ws/1/track/MBID</nowiki></code> || An individual track
| <code><nowiki>http://musicbrainz.org/ws/1/track/MBID</nowiki></code> || An individual track
|-
| <code><nowiki>http://musicbrainz.org/ws/1/label/</nowiki></code> || Collection of all labels
|-
| <code><nowiki>http://musicbrainz.org/ws/1/label/MBID</nowiki></code> || An individual label
|-
| <code><nowiki>http://musicbrainz.org/ws/1/tag/</nowiki></code> || Folksonomy tags
|-
| <code><nowiki>http://musicbrainz.org/ws/1/rating/</nowiki></code> || Ratings
|}
|}


Basically, there are two different ways to access [[MusicBrainz]] data. If you know the MBID (a globally unique identifier assigned to each object in the database), you can request the resource directly. To access the artist "Tori Amos" for example, the resource <code><nowiki>http://musicbrainz.org/ws/1/artist/c0b2500e-0cef-4130-869d-732b23ed9df5</nowiki></code> may be used.
Basically, there are two different ways to access [[MusicBrainz]] data. If you know the MBID (a globally unique identifier assigned to each object in the database), you can request the resource directly. To access the artist "Tori Amos" for example, the resource <code><nowiki>http://musicbrainz.org/ws/1/artist/c0b2500e-0cef-4130-869d-732b23ed9df5?type=xml</nowiki></code> may be used.


Another option is to use the <code><nowiki>artist</nowiki></code> collection. Since this collection is huge, it is unfeasible to request all of it and then extract the data you need. Instead, collections support ''filters'', which allow to limit the amount of data based on some criteria. For example, you can use a filter to only request artists with the name "Tori Amos": <code><nowiki>http://musicbrainz.org/ws/1/artist/?type=xml&name=Tori+Amos</nowiki></code>. The Filters supported depend on the collection and are described below.
Another option is to use the <code>artist</code> collection. Since this collection is huge, it is unfeasible to request all of it and then extract the data you need. Instead, collections support ''filters'', which allow to limit the amount of data based on some criteria. For example, you can use a filter to only request artists with the name "Tori Amos": <code><nowiki>http://musicbrainz.org/ws/1/artist/?type=xml&name=Tori+Amos</nowiki></code>. The Filters supported depend on the collection and are described below. Data returned from collections will also have an <code><nowiki>ext:rating value="[rating]"</nowiki></code> attribute that indicates the rating returned from the search engine -- the rating value is between 0 and 100.


In REST, HTTP methods are used to create (<code><nowiki>PUT</nowiki></code>), retrieve (<code><nowiki>GET</nowiki></code>), modify (<code><nowiki>POST</nowiki></code>) and delete (<code><nowiki>DELETE</nowiki></code>) resources. The most important method for this web service is <code><nowiki>GET</nowiki></code>, which returns a ''representation'' for the requested resource. Several different representations are possible, but at this point only the XML format discussed later in this document is supported.
In REST, HTTP methods are used to create (<code>POST</code>), retrieve (<code>GET</code>), modify (<code>PUT</code>) and delete (<code>DELETE</code>) resources. The most important method for this web service is <code>GET</code>, which returns a ''representation'' for the requested resource. Several different representations are possible, but at this point only the XML format discussed later in this document is supported.


By default, the web service only returns a basic representation of a resource. Additional information can be requested using the <code><nowiki>inc</nowiki></code> parameter, which depends on the resource. If you want to request a release including all tracks and additional release information for example, you can use this URL: <code><nowiki>http://musicbrainz.org/ws/1/release/02232360-337e-4a3f-ad20-6cdd4c34288c?type=xml&inc=tracks+release-events</nowiki></code>
By default, the web service only returns a basic representation of a resource. Additional information can be requested using the <code>inc</code> parameter, which depends on the resource. If you want to request a release including all tracks and additional release events for example, you can use this URL: <code><nowiki>http://musicbrainz.org/ws/1/release/02232360-337e-4a3f-ad20-6cdd4c34288c?type=xml&inc=tracks+release-events</nowiki></code>


The following sections discuss the parameters available for each type of resource. The <code><nowiki>type</nowiki></code> parameter is required for all web service queries:
The following sections discuss the parameters available for each type of resource. The <code>type</code> parameter is required for all web service queries:
{| border="1"
{| border="1"
|-
|-
| type || Selects the representation of the resource. Currently only <code><nowiki>xml</nowiki></code> is supported. '''This is mandatory!'''
| '''type''' || Selects the representation of the resource. Currently only <code>xml</code> is supported. '''This is mandatory!'''
|}
|}


The <code><nowiki>inc</nowiki></code> parameter is only allowed for individual resources (but not for collections):
The <code>inc</code> parameter is <u>only allowed for individual resources</u> (but not for collections):
{| border="1"
{| border="1"
|-
|-
| inc || A list of space separated values describing how much detail should be included in the output. If there is no <code><nowiki>inc</nowiki></code> parameter, just the basic data for a resource is returned. For artists that would be name, sort-name, and disambiguation.
| '''inc''' || A list of space separated values describing how much detail should be included in the output. If there is no <code>inc</code> parameter, just the basic data for a resource is returned. For artists that would be name, sort-name, and disambiguation.
|}
|}


The <code><nowiki>limit</nowiki></code> parameter is supported for all resource collections (but not for individual resources):
The <code>limit</code>, <code>offset</code> and <code>query</code> parameters are <u>supported for all resource collections</u> (but not for individual resources):
{| border="1"
{| border="1"
|-
|-
| limit || An integer value defining how many entries should be returned. Only values between 1 and 100 (both inclusive) are allowed. If not given, this defaults to 25.
| '''limit''' || An integer value defining how many entries should be returned. Only values between 1 and 100 (both inclusive) are allowed. If not given, this defaults to 25.
|-
| '''offset''' || Return search results starting at a given offset. Used for paging through more than one page of results.
|-
| '''query''' || A lucene search query. If this is given, then all other collection/filter arguments are ignored, you need to use the field names as detailed in [[Text Search Syntax|TextSearchSyntax]]
|}
|}


Line 98: Line 119:
| 400 Bad Request || Syntactically invalid MBID requested.
| 400 Bad Request || Syntactically invalid MBID requested.
|-
|-
| || Invalid parameter value (ie. invalid <code><nowiki>inc</nowiki></code> tag)
| || Invalid parameter value (ie. invalid <code>inc</code> tag)
|-
|-
| || Missing required parameter value (ie. <code><nowiki>type</nowiki></code> not set)
| || Missing required parameter value (ie. <code>type</code> not set)
|-
|-
| 401 Unauthorized || Client requested a resource which requires authentication via HTTP Digest Authentication.
| 401 Unauthorized || Client requested a resource which requires authentication via HTTP Digest Authentication.
Line 106: Line 127:
| || If sent even though user name and password were given: user name and/or password are incorrect.
| || If sent even though user name and password were given: user name and/or password are incorrect.
|-
|-
| 404 Not Found || Wrong web service prefix. <code><nowiki>/ws/</nowiki></code> would be correct for the [[MusicBrainz]] server.
| 404 Not Found || Wrong web service prefix. <code>/ws/</code> would be correct for the [[MusicBrainz]] server.
|-
|-
| || Invalid version number. Only version <code><nowiki>1</nowiki></code> is currently supported.
| || Invalid version number. Only version <code>1</code> is currently supported.
|-
|-
| || Invalid entity name. Only <code><nowiki>artist</nowiki></code>, <code><nowiki>release</nowiki></code>, <code><nowiki>track</nowiki></code>, or <code><nowiki>user</nowiki></code> are permitted.
| || Invalid entity name. Only <code>artist</code>, <code>release</code>, <code>track</code>, or <code>user</code> are permitted.
|-
|-
| || Resource not found. There is no resource having this ID (maybe it was merged or deleted).
| || Resource not found. There is no resource having this ID (maybe it was merged or deleted).
Line 117: Line 138:
==artist resources==
==artist resources==


===Looking up a Specific Artist===
Parameters for http<code><nowiki></nowiki></code>://musicbrainz.org/ws/1/artist/''MBID'':

Parameters for <code><nowiki>http://musicbrainz.org/ws/1/artist/</nowiki>''MBID''</code>:
{| border="1"
{| border="1"
|-
|-
| inc || Supported: 'aliases', 'sa-'*, 'va-'*, 'artist-rels', 'release-rels', 'track-rels', 'url-rels'
| inc || Supported: 'aliases', 'release-groups', 'sa-'*, 'va-'*, 'artist-rels', 'label-rels', 'release-rels', 'track-rels', 'url-rels', 'tags', 'ratings', 'user-tags', 'user-ratings', 'counts', 'release-events', 'discs', 'labels'
|}
|}


Example: [http://musicbrainz.org/ws/1/artist/c0b2500e-0cef-4130-869d-732b23ed9df5?type=xml&inc=url-rels+artist-rels http://musicbrainz.org/ws/1/artist/c0b2500e-0cef-4130-869d-732b23ed9df5?type=xml&inc=url-rels+artist-rels]
To get an artist's releases, the 'sa-' and 'va-' prefixes (for single artist and various artist releases, respectively) together with the desired release type have to be used. For example, the release tag <code><nowiki>sa-Album</nowiki></code> requests single artist albums, while <code><nowiki>va-Bootleg</nowiki></code> requests various artists bootlegs. Multiple tags may be used, so <code><nowiki>inc=sa-Compilation+sa-Official</nowiki></code> is valid and returns all official compilations by that artist (''AND'' conjunctions are used for release types!).


'''Note''':
'''Note''': Only 'sa-' ''or'' 'va-' may be used in an <code><nowiki>inc</nowiki></code> parameter.


When looking up a specific artist MBID, while any of the other <code>inc</code> parameters may be used in any combinations, only one of 'sa-' '''or''' 'va-' may be used in any given query.
Parameters for http<code><nowiki></nowiki></code>://musicbrainz.org/ws/1/artist/:

===Searching Artists===

Parameters for <code><nowiki>http://musicbrainz.org/ws/1/artist/</nowiki></code>:
{| border="1"
{| border="1"
|-
|-
Line 133: Line 160:
|-
|-
| limit || The maximum number of artists returned. Defaults to 25, the maximum allowed value is 100.
| limit || The maximum number of artists returned. Defaults to 25, the maximum allowed value is 100.
|}

Example: [http://musicbrainz.org/ws/1/artist/?type=xml&name=Tori+Amos http://musicbrainz.org/ws/1/artist/?type=xml&name=Tori+Amos]

==='sa-' and 'va-'===

To get an artist's releases, the 'sa-' and 'va-' prefixes (for single artist and various artist releases, respectively) together with the desired release type have to be used. For example, the release tag <code>sa-Album</code> requests single artist releases, while <code>va-Bootleg</code> requests various artists bootlegs. Multiple tags may be used, so <code>inc=sa-Compilation+sa-Official</code> is valid and returns all official compilations by that artist (''AND'' conjunctions are used for release types!).

==release group resources==

===Looking up a Specific Release Group===

Parameters for <code><nowiki>http://musicbrainz.org/ws/1/release-group/</nowiki>''MBID''</code>:
{| border="1"
|-
| inc || Supported: 'artist', 'releases'
|}

===Searching Release Groups===

Parameters for <code><nowiki>http://musicbrainz.org/ws/1/release-group/</nowiki></code>:
{| border="1"
|-
| title || Fetch a list of release groups with a matching title
|-
| artist || The returned release groups should match the given artist name
|-
| artistid || The returned release groups should match the given artist ID (36 character ASCII representation). If this is given, the <code>artist</code> parameter is ignored.
|-
| releasetypes || The returned release groups must match all of the given release types. This is a list of space separated values like <code>Official</code>, <code>Bootleg</code>, <code>Album</code>, <code>Compilation</code>, etc.
|-
| limit || The maximum number of release groups returned. Defaults to 25, the maximum allowed value is 100.
|}
|}


==release resources==
==release resources==


===Looking up a Specific Release===
Parameters for http<code><nowiki></nowiki></code>://musicbrainz.org/ws/1/release/''MBID'':

Parameters for <code><nowiki>http://musicbrainz.org/ws/1/release/</nowiki>''MBID''</code>:
{| border="1"
{| border="1"
|-
|-
| inc || Supported: 'artist', 'counts', 'release-events', 'discs', 'tracks', 'artist-rels', 'release-rels', 'track-rels', 'url-rels'
| inc || Supported: 'artist', 'counts', 'release-events', 'discs', 'tracks', 'release-groups', 'artist-rels', 'label-rels', 'release-rels', 'track-rels', 'url-rels', 'track-level-rels', 'labels', 'tags', 'ratings', 'user-tags', 'user-ratings', 'isrcs'
|}
|}


===Searching Releases===
Parameters for http<code><nowiki></nowiki></code>://musicbrainz.org/ws/1/release/:

Parameters for <code><nowiki>http://musicbrainz.org/ws/1/release/</nowiki></code>:
{| border="1"
{| border="1"
|-
|-
Line 152: Line 215:
| artist || The returned releases should match the given artist name
| artist || The returned releases should match the given artist name
|-
|-
| artistid || The returned releases should match the given artist ID (36 character ASCII representation). If this is given, the <code><nowiki>artist</nowiki></code> parameter is ignored.
| artistid || The returned releases should match the given artist ID (36 character ASCII representation). If this is given, the <code>artist</code> parameter is ignored.
|-
|-
| releasetypes || The returned releases must match all of the given release types. This is a list of space separated values like <code><nowiki>Official</nowiki></code>, <code><nowiki>Bootleg</nowiki></code>, <code><nowiki>Album</nowiki></code>, <code><nowiki>Compilation</nowiki></code>, etc.
| releasetypes || The returned releases must match all of the given release types. This is a list of space separated values like <code>Official</code>, <code>Bootleg</code>, <code>Album</code>, <code>Compilation</code>, etc.
|-
| count || Number of tracks in the release
|-
| date || Earliest release date for the release
|-
| asin || The Amazon ASIN
|-
| lang || The language for this release
|-
| script || The script used this release
|-
| cdstubs || Indicates whether to include [[CDStub|CD stubs]] in the result or not. Can be set to "yes" or "no". By default CD stubs are included.
|-
|-
| limit || The maximum number of releases returned. Defaults to 25, the maximum allowed value is 100.
| limit || The maximum number of releases returned. Defaults to 25, the maximum allowed value is 100.
|}
|}


For the <code><nowiki>releasetypes</nowiki></code> parameter, the [[MusicBrainz]] release type and release status values are used (see [[Album Attribute|AlbumAttribute]]). Note that the current [[MusicBrainz]] server only supports ''one'' release type and ''one'' release status value, so for example <code><nowiki>releasetypes=Live+Compilation</nowiki></code> won't work because for <code><nowiki>releasetypes</nowiki></code> an AND conjunction is used.
For the <code>releasetypes</code> parameter, the [[MusicBrainz]] release type and release status values are used (see [[Release Attribute|ReleaseAttribute]]). Note that the current [[MusicBrainz]] server only supports ''one'' release type and ''one'' release status value, so for example <code>releasetypes=Live+Compilation</code> won't work because for <code>releasetypes</code> an AND conjunction is used.

Please note, that additional information like the track artist is only given once for a specific track/recording. If the same track/recording appears in another release in the results, no track artist will be given again. You can build a dictionary for the tracks, indexed by "track id" (which is a recording id actually) and check if information for a track was given earlier.

===Submitting a CDStub===

Parameters for posting to <code><nowiki>http://musicbrainz.org/ws/1/release/</nowiki></code>:
{| border="1"
|-
| title || Title of the release
|-
| discid || DiscID of the release
|-
| toc || TOC of the release
|-
| artist || Artist of the release
|-
| client || The ID of the client software submitting the CDStub. This has to be the application's name and version number, ''not'' that of a client library (client libraries should use HTTP's <code>User-Agent</code> header)! The required format: <code>application-version</code>, where version ''must not'' contain a <code><nowiki>-</nowiki></code> character.
|-
| barcode || Barcode of the release (optional)
|-
| comment || Comment for the release (optional)
|}

For each track:
{| border="1"
|-
| track''N'' || Title of the Nth track in the release
|-
| artist''N'' || Artist of the Nth track in the release (for Various Artists release)
|}

Example:
* Single artist release: <code><nowiki>http://musicbrainz.org/ws/1/release/?client=<client>&title=<title>&artist=<sa-artist>&toc=<toc>&discid=<discid>&barcode=<barcode>&comment=<comment>&track0=<track0>&track1=<track1>...</nowiki></code>
* Various artists release: <code><nowiki>http://musicbrainz.org/ws/1/release/?client=<client>&title=<title>&toc=<toc>&discid=<discid>&barcode=<barcode>&comment=<comment>&track0=<track0>&artist0=<artist0>&track1=<track1>&artist1=<artist1>...</nowiki></code>


==track resources==
==track resources==


===Looking up a Specific Track===
Parameters for http<code><nowiki></nowiki></code>://musicbrainz.org/ws/1/track/''MBID'':

Parameters for <code><nowiki>http://musicbrainz.org/ws/1/track/</nowiki>''MBID''</code>:
{| border="1"
{| border="1"
|-
|-
| inc || Supported: 'artist', 'releases', 'puids', 'artist-rels', 'release-rels', 'track-rels', 'url-rels'
| inc || Supported: 'artist', 'releases', 'puids', 'artist-rels', 'label-rels', 'release-rels', 'track-rels', 'url-rels', 'tags', 'ratings', 'user-tags', 'user-ratings', 'isrcs'
|}
|}


===Searching Tracks===
Parameters for http<code><nowiki></nowiki></code>://musicbrainz.org/ws/1/track/:

Parameters for <code><nowiki>http://musicbrainz.org/ws/1/track/</nowiki></code>:
{| border="1"
{| border="1"
|-
|-
Line 180: Line 293:
| duration || The length of the track in milliseconds
| duration || The length of the track in milliseconds
|-
|-
| tracknum || The track number
| tracknumber || The track number
|-
|-
| artistid || The artist's MBID. If this is given, the <code><nowiki>artist</nowiki></code> parameter is ignored.
| artistid || The artist's MBID. If this is given, the <code>artist</code> parameter is ignored.
|-
|-
| releaseid || The release's MBID. If this is given, the <code><nowiki>release</nowiki></code> parameter is ignored.
| releaseid || The release's MBID. If this is given, the <code>release</code> parameter is ignored.
|-
|-
| puid || The returned tracks have to match the given PUID.
| puid || The returned tracks have to match the given PUID. Note that when searching by this field, all other parameter values are ignored and cannot be used to further filter the results. PUID should be used on its own.
|-
| count || Number of tracks on the release
|-
| releasetype || The type of the release this track appears on
|-
|-
| limit || The maximum number of tracks returned. Defaults to 25, the maximum allowed value is 100.
| limit || The maximum number of tracks returned. Defaults to 25, the maximum allowed value is 100.
|}
|}


===PUID submission===
PUID submission works using <code><nowiki>POST</nowiki></code> on the collection of tracks. The parameters are sent url-encoded, that means with a content type of <code><nowiki>application/x-www-form-urlencoded</nowiki></code>.


PUID submission works using <code>POST</code> on the collection of tracks. The parameters are sent url-encoded, that means with a content type of <code>application/x-www-form-urlencoded</code>.
Parameters for posting to http<code><nowiki></nowiki></code>://musicbrainz.org/ws/1/track/:

Parameters for posting to <code><nowiki>http://musicbrainz.org/ws/1/track/</nowiki></code>:
{| border="1"
{| border="1"
|-
|-
| client || The ID of the client software submitting the PUIDs. This has to be the application's name and version number, ''not'' that of a client library (client libraries should use HTTP's <code><nowiki>User-Agent</nowiki></code> header)! The required format: <code><nowiki>application-version</nowiki></code>, where version ''must not'' contain a <code><nowiki>-</nowiki></code> character.
| client || The ID of the client software submitting the PUIDs. This has to be the application's name and version number, ''not'' that of a client library (client libraries should use HTTP's <code>User-Agent</code> header)! The required format: <code>application-version</code>, where version ''must not'' contain a <code><nowiki>-</nowiki></code> character.
|-
|-
| puid || A (TrackId, PUIDId) pair, separated by a single space character. Both TrackId and PUID are in their 36 character ASCII representation. This parameter may appear multiple times.
| puid || A (TrackId, PUIDId) pair, separated by a single space character. Both TrackId and PUID are in their 36 character ASCII representation. This parameter may appear multiple times.
|}
|}


Please consider batching multiple PUID submissions into one web service call. Not only does this reduce the number of web service calls, it reduces the number of edits stored in the database.
Users have to be logged in to submit PUIDs. This is independent from the website login and works via HTTP Digest Authentication. The realm is 'musicbrainz.org'.


Users have to be logged in to submit PUIDs. This is independent from the website login and works via HTTP Digest Authentication. The realm is 'musicbrainz.org'.
==Examples==


===ISRC submission===
Below are a few user contributed examples to illustrate the use of this web service:


[[ISRC]] submission works very similar to the PUID submission by using <code>POST</code> on the collection of tracks. The parameters are sent url-encoded, that means with a content type of <code>application/x-www-form-urlencoded</code>.
To get the Official XTC Releases that best match the album title "Wasp Star Apple Venus Volume 2", this would be the query: <code><nowiki>http://musicbrainz.org/ws/1/release/?type=xml&artist=XTC&releasetypes=Official&limit=10&title=Wasp+Star+Apple+Venus+Vol+2</nowiki></code>


Tracks listing can then be gotten by choosing the release id and querying for tracks: <code><nowiki>http://musicbrainz.org/ws/1/release/6d931ac2-e389-4e99-8a01-1da65162c372?type=xml&inc=tracks</nowiki></code>
Parameters for posting to <code><nowiki>http://musicbrainz.org/ws/1/track/</nowiki></code>:
{| border="1"
|-
| isrc || A (TrackId, ISRC) pair, separated by a single space character. Both TrackId is in its 36 character ASCII representation and ISRC is ASCII formatted according to [[ISRC|ISRC formatting rules]]. This parameter may appear multiple times.
|}


Please batch multiple ISRC submissions into one web service call. Not only does this reduce the number of web service calls, it reduces the number of edits stored in the database.
=The XML Format=


Users have to be logged in to submit ISRCs. This is independent from the website login and works via HTTP Digest Authentication. The realm is 'musicbrainz.org'.
To represent web service responses, which are basically representations of some part of the [[MusicBrainz]] database, a new XML format has been developed. It is easy to read, powerful and extensible. Unfortunately, there is no documentation on it yet, but some examples and a [http://www.relaxng.org/ Relax NG schema] are available via [http://subversion.tigris.org subversion]:


==label resources==
<code><nowiki>svn co http://svn.musicbrainz.org/mmd-schema/trunk mmd-schema</nowiki></code>


===Looking up a Specific Label===
This is also available via the [http://bugs.musicbrainz.org/browser/mmd-schema/trunk trac source browser].


Parameters for <code><nowiki>http://musicbrainz.org/ws/1/label/</nowiki>''MBID''</code>:
Bugs in the schema should be reported on the IRC channel or posted to mb-devel. Please note that we're not going to make major changes to the format, only remaining mistakes will be corrected.
{| border="1"
|-
| inc || Supported: 'aliases', 'artist-rels', 'label-rels', 'release-rels', 'track-rels', 'url-rels', 'tags', 'ratings', 'user-tags', 'user-ratings'
|}


==IDs and Types==
===Searching Labels===


Parameters for <code><nowiki>http://musicbrainz.org/ws/1/label/</nowiki></code>:
The IDs and types used in the XML format are URIs. To keep the transmission overhead low, all URIs in the [[MusicBrainz]] namespace may be used in their ''relative'' form. So if a track's fully qualified <code><nowiki>id</nowiki></code> is <code><nowiki>http://musicbrainz.org/track/d6118046-407d-4e06-a1ba-49c399a4c42f</nowiki></code>, it may be shortened to <code><nowiki>d6118046-407d-4e06-a1ba-49c399a4c42f</nowiki></code> in the XML. Note that this shortening is only allowed for URIs from the [[MusicBrainz]] namespace.
{| border="1"
|-
| name || Fetch a list of labels with a matching name
|-
| limit || The maximum number of labels returned. Defaults to 25, the maximum allowed value is 100.
|}


==folksonomy resources==
The following rules apply to create a fully qualified URI from a relative one:
* The <code><nowiki>id</nowiki></code> attributes:
** artist: <code><nowiki>http://musicbrainz.org/artist/</nowiki></code>'''relative URI'''
** release: <code><nowiki>http://musicbrainz.org/release/</nowiki></code>'''relative URI'''
** track: <code><nowiki>http://musicbrainz.org/track/</nowiki></code>'''relative URI'''


This requires you to be logged in and shown only your own tags. In order to see other tags use the other resources with the parameter inc=tags as described above.
* The <code><nowiki>type</nowiki></code> attributes:
** artist: <code><nowiki>http://musicbrainz.org/ns/mmd-1.0#</nowiki></code>'''relative URI'''
** release: <code><nowiki>http://musicbrainz.org/ns/mmd-1.0#</nowiki></code>'''relative URI''' (for each relative URI in the list)


===Looking up tags for a Specific Entity===
Due to their large number, relations are in a namespace on their own to avoid clashes:
* Various relation attributes:
** type: <code><nowiki>http://musicbrainz.org/ns/rel-1.0#</nowiki></code>'''relative URI'''
** attributes: <code><nowiki>http://musicbrainz.org/ns/rel-1.0#</nowiki></code>'''relative URI''' (for each relative URI in the list)


Parameters for <code><nowiki>http://musicbrainz.org/ws/1/tag/</nowiki></code>:
'''Note''': Don't confuse the URIs, especially the <code><nowiki>id</nowiki></code> URIs with URLs. The URIs are just names, they should not be used to query data from the server. But they are in a permanent format which will always be valid and can easily be transformed to URLs. Example:
{| border="1"
|-
| id || The MBID of the entity that you would like to see your tags for, this could be a track ID, release ID, artist ID or label ID
|-
| entity || Identifies the entity type, can be artist, release, track or label
|}


Example: <code><nowiki>http://musicbrainz.org/ws/1/tag/?id=5fc9f3d4-8f61-4f35-a20a-f8a0cae84d46&type=xml&entity=artist</nowiki></code> (this will show an empty list of tags unless you have tagged this artist)
The following is an absolute, permanent [[MusicBrainz]] artist identifier which is the preferred representation. Shorter representations may be used for storing IDs in file tags or databases.


===Tags submission===
<pre> http://musicbrainz.org/artist/c0b2500e-0cef-4130-869d-732b23ed9df5
</pre>


Folksonomy tag submission works using <code>POST</code> on the collection of tags. The parameters are sent url-encoded, that means with a content type of <code>application/x-www-form-urlencoded</code>.
This one is a URL created from the URI above, using a simple transformation. It can be used to request data from the [[MusicBrainz]] server via the webservice. URLs may change over time, the URIs will not.


<pre> http://musicbrainz.org/ws/1/artist/c0b2500e-0cef-4130-869d-732b23ed9df5
Parameters for posting to <code><nowiki>http://musicbrainz.org/ws/1/tag/</nowiki></code>:
</pre>


====Simple submission====
==Using the XML format for other applications==


{| border="1"
The XML format format uses URIs for several IDs and types. The <code><nowiki>artist</nowiki></code> element, for example, has a <code><nowiki>type</nowiki></code> attribute which accepts a URI. Users of the format may use the URIs defined by [[MusicBrainz]] or use one from their own namespace. This example uses a definition from [[MusicBrainz]]:
|-
| id || The MBID of the entity you are adding tags to, this could be a track ID, release ID, artist ID or label ID
|-
| entity || Identifies the entity type, can be artist, release, track or label
|-
| tags || Comma separated list of tags to be added
|}

====Batch submission====

You can tag up to 20 different entities at the same time.

For each entity, if entity is the Nth you're submitting:
{| border="1"
|-
| id.''N'' || The MBID of the Nth entity you are adding tags to, this could be a track ID, release ID, artist ID or label ID
|-
| entity.''N'' || Identifies the Nth entity type, can be artist, release, track or label
|-
| tags.''N'' || Comma separated list of tags to be added
|}

Example: <code><nowiki>http://musicbrainz.org/ws/1/tag/?entity.0=<entity-type>&id.0=<mbid>&tags.0=<tags>&entity.1=<entity-type>&id.1=<mbid>&tags.1=<tags>...</nowiki></code>

Users have to be logged in to submit tags. This is independent from the website login and works via HTTP Digest Authentication. The realm is 'musicbrainz.org'.

==ratings resources==

This requires you to be logged in and shown only your own ratings. In order to see other ratings use the other resources with the parameter inc=ratings as described above.

===Looking up rating for a Specific Entity===

Parameters for <code><nowiki>http://musicbrainz.org/ws/1/rating/</nowiki></code>:
{| border="1"
|-
| id || The MBID of the entity that you would like to see your rating for, this could be a track ID, release ID, artist ID or label ID
|-
| entity || Identifies the entity type, can be artist, release, track or label
|}

Example: <code><nowiki>http://musicbrainz.org/ws/1/rating/?id=5fc9f3d4-8f61-4f35-a20a-f8a0cae84d46&type=xml&entity=artist</nowiki></code> (this will show an empty rating unless you have rated this artist)

===Ratings submission===

Rating submission works using <code>POST</code> on the collection of ratings. The parameters are sent url-encoded, that means with a content type of <code>application/x-www-form-urlencoded</code>.

Parameters for posting to <code><nowiki>http://musicbrainz.org/ws/1/rating/</nowiki></code>:

====Simple submission====

{| border="1"
|-
| id || The MBID of the entity that you are rating, this could be a track ID, release ID, artist ID or label ID
|-
| entity || Identifies the entity type, can be artist, release, track or label
|-
| rating || Integer between 0 and 5 (actually 1-5 are ratings values, 0 is equivalent to unrating)
|}

====Batch submission====

You can rate up to 20 different entities at the same time.

For each entity, if entity is the Nth you're submitting:
{| border="1"
|-
| id.''N'' || The MBID of the Nth entity that you are rating, this could be a track ID, release ID, artist ID or label ID
|-
| entity.''N'' || Identifies the Nth entity type, can be artist, release, track or label
|-
| rating.''N'' || Integer between 0 and 5 (actually 1-5 are ratings values, 0 is equivalent to unrating)
|}

Example: <code><nowiki>http://musicbrainz.org/ws/1/rating/?entity.0=<entity-type>&id.0=<mbid>&rating.0=<rating>&entity.1=<entity-type>&id.1=<mbid>&rating.1=<rating>...</nowiki></code>

Users have to be logged in to submit ratings. This is independent from the website login and works via HTTP Digest Authentication. The realm is 'musicbrainz.org'.

==user collection resources==

''User collections'' are different from ''collections'' that contain artists, releases, tracks and labels. User collections refer to the MusicBrainz feature that allows users to store information about their personal music collections. Using the user collections resource you can add/removes releases or list your music collection.

You can only remove or add releases in one call, you cannot do both in one call.

NOTES: Using a GET was previously possible for adding and removing releases. This has been disallowed and future releases of the web service will not allow these operations with a GET method. If you have an existing application that uses a GET, please change it as soon as possible.

===Adding releases===

Parameters for <code><nowiki>http://musicbrainz.org/ws/1/collection/</nowiki></code>:
{| border="1"
|-
| add || A list of Releases MBIDs you'd like to add to your collection, separated by commas.
|}

Example: <code><nowiki>http://musicbrainz.org/ws/1/collection/?add=cac64a87-42f9-4c1c-a5ef-1e6824e20678,cac64a87-42f9-4c1c-a5ef-1e6824e20678,cac64a87-42f9-4c1c-a5ef-1e6824e20678</nowiki></code>

===Removing releases===

Parameters for <code><nowiki>http://musicbrainz.org/ws/1/collection/</nowiki></code>:
{| border="1"
|-
| remove || A list of Releases MBIDs you'd like to remove from your collection, separated by commas.
|}

Example: <code><nowiki>http://musicbrainz.org/ws/1/collection/?remove=cac64a87-42f9-4c1c-a5ef-1e6824e20678,cac64a87-42f9-4c1c-a5ef-1e6824e20678,cac64a87-42f9-4c1c-a5ef-1e6824e20678</nowiki></code>

===List releases in collection===

A list of albums in a users collection is returned from the collection resource when no arguments are supplied:

<code><nowiki>http://musicbrainz.org/ws/1/collection/</nowiki></code> returns xml shown in the next section.

A maximum of 100 items will be returned for any one call to the collection resource. In order to fetch more than 100 items, please use the <code>offset</code> and <code>maxitems</code> parameters:

{| border="1"
|-
| offset || The offset into the collection where to return releases from.
|-
| maxitems || The maximum number of items to return. This cannot be more than 100.
|}


===XML response===
<pre> <artist id="c0b2500e-0cef-4130-869d-732b23ed9df5" type="http://musicbrainz.org/ns/mmd-1.0#Group"/>
</pre>


The XML response for all of the three collection actions is shown below. For a add/remove operation only the MBIDs of added/removed releases will be returned. When no action is given (list), all releases in the collection will be returned.
If an application needs "Orchestra" as an artist type, a different namespace may be used:


<pre><?xml version="1.0" encoding="UTF-8"?>
<pre> <artist id="c0b2500e-0cef-4130-869d-732b23ed9df5" type="http://example.org/ext-7.2#Orchestra"/>
<metadata xmlns="http://musicbrainz.org/ns/mmd-1.0#">
</pre>
<release-list count="3">
<release id="cac64a87-42f9-4c1c-a5ef-1e6824e20678"/>
<release id="b71926ec-5813-4fa4-9372-0c07154a07af"/>
<release id="172ddda3-1837-4fd2-8d12-ddd1e70b4c57"/>
</release-list>
</metadata></pre>


For listing the collection, the count attribute in the release-list element indicates the total number of releases in the collection.
This method may be used in all places where the schema accepts an anyURI datatype. As mentioned earlier, there is a special rule for all URIs defined by [[MusicBrainz]]: They may be ''relative'', as you can see in the examples above. The complete artist ids have the form <code><nowiki>http://musicbrainz.org/artist/c0b2500e-0cef-4130-869d-732b23ed9df5</nowiki></code> and the <code><nowiki>type</nowiki></code> attribute in the first example could also be written as <code><nowiki>Group</nowiki></code>, without the namespace prefix.


=The Resource Representation=
To extend the format even further, the schema has several extension points (see <code><nowiki>def_extension</nowiki></code>) which allows adding arbitrary XML elements from a user-defined namespace. Using the mmd-namespace or no namespace at all is not permitted. There are no namespace restrictions inside that element, however, and unlimited nesting is possible, too.


As mentioned above, the <code>type</code> parameter selects the representation of the returned resources. At this point, the only available representation is <code>xml</code>. All returned data is in a newly developed XML-based language, the [[MusicBrainz XML Meta Data|MusicBrainz XML Metadata Format]].
If your private namespace is <code><nowiki>http://example.org/ext-9.1#</nowiki></code> and you want to add data from a rating system, for example, it could be coded like this:


=Limiting Connections to the MusicBrainz Web Service=
<pre><?xml version="1.0" encoding="UTF-8"?>
<metadata xmlns="http://musicbrainz.org/ns/mmd-1.0#" xmlns:ext="http://example.org/ext-9.1#">
<track id="d6118046-407d-4e06-a1ba-49c399a4c42f">
<title>Silent All These Years</title>
<duration>253466</duration>
<ext:rating value="9"/>
</track>
</metadata>
</pre>


All users of the XML web service must ensure that each of their client applications never make more than ONE web service call per second. Making more than one call per second drives up the load on the servers and prevents others from using MusicBrainz. If you impact the server by making more than one call per second, your IP address may be blocked preventing all further access to MusicBrainz. For more details on this, please see our [[XML_Web_Service/Rate_Limiting|rate limiting page]].
Even more complicated things, like nested tags are possible. Note that the <code><nowiki>em</nowiki></code> doesn't belong to the <code><nowiki>ext</nowiki></code> namespace.


=Identifying your application to the MusicBrainz Web Service=
<pre><?xml version="1.0" encoding="UTF-8"?>
<metadata xmlns="http://musicbrainz.org/ns/mmd-1.0#" xmlns:ext="http://example.org/ext-9.1#">
<track id="d6118046-407d-4e06-a1ba-49c399a4c42f">
<title>Silent All These Years</title>
<duration>253466</duration>
<ext:annotation>This is a <em>very</em> nice song.</ext:annotation>
</track>
</metadata>
</pre>


It is important that your application set a proper User-Agent string in its HTTP request headers. Please read our [[XML_Web_Service/Rate_Limiting|rate limiting]] documentation for more details.
This is still valid according to the schema, but inside the extension elements, only well-formedness can be checked.


=A Note to Application Developers=
=A Note to Application Developers=
Line 298: Line 534:
The [[python-musicbrainz2|PythonMusicBrainz2]] package is the reference implementation of a client library for this web service. It has been designed to be as simple to use as possible but still provides access to all parts of the service. If you are planning to write bindings for another programming language, you are encouraged to follow the programming model, object oriented schema, and terminology of [[python-musicbrainz2|PythonMusicBrainz2]] as far as it makes sense for your language.
The [[python-musicbrainz2|PythonMusicBrainz2]] package is the reference implementation of a client library for this web service. It has been designed to be as simple to use as possible but still provides access to all parts of the service. If you are planning to write bindings for another programming language, you are encouraged to follow the programming model, object oriented schema, and terminology of [[python-musicbrainz2|PythonMusicBrainz2]] as far as it makes sense for your language.


List of known implementations:
----
* Python: [[python-musicbrainz2]]
* C/C++: [[libmusicbrainz|libmusicbrainz 3.x]] (the current version of libmusicbrainz supports the current web service)
* Perl: [http://search.cpan.org/dist/WebService-MusicBrainz/ WebService::MusicBrainz]
* PHP: [[phpbrainz]] (there is a fork available for WS/2: [https://github.com/mikealmond/MusicBrainz mikealmond/MusicBrainz])
* Ruby: [http://rbrainz.rubyforge.org RBrainz]
* C#/.Net:
** [[Musicbrainz Sharp|musicbrainz-sharp]]
** [http://www.ok-edv.de library by ok-edv]
* Java: [http://svn.musicbrainz.org/libmusicbrainz-java/trunk/ libmusicbrainz-java]


Please don't start new development using these libraries.
There are libraries available for the [[Development/XML Web Service/Version 2#3rd party libraries|current web service]].


----


=Development Notes=
=Development Notes=


The following sections are informal. They are not part of the specification.
This section has to be integrated into the spec at some point.


==Use Cases==
==Use Cases==


This new web service will have the following use cases:
This new web service will have the following use cases:
* Retrieve artist (via mbid)/album (via mbid/cdid)/track (via mbid)
* Retrieve artist (via mbid)/release (via mbid/cdid)/track (via mbid)
** Each of these should return a minimal amount of data and have options to return more detailed data:
** Each of these should return a minimal amount of data and have options to return more detailed data:
*** artist: optional list of albums
*** artist: optional list of releases
*** album: optional artist info, cdids, release info, list of tracks
*** release: optional artist info, cdids, release events, list of tracks
*** track: optional artist info
*** track: optional artist info


Line 324: Line 573:
* Lookup track (like MBQ_FileLookup)
* Lookup track (like MBQ_FileLookup)


==Collection filtering issues==
==Collection filtering notes==


Resource collections are '''not''' handled by the database, but by our Lucene search engine. This means that the data returned by collection queries may not be fully up to date, as the search indexes get computed once a day.
The exact collection filtering hasn't been defined yet. I think tying query fields together using logical OR is probably the best choice. Lucene will automatically move the best matches to the top of the result list. However, there should be one exception: If IDs are given (artistid, releaseid, discid, puid), then the results should always match those IDs. An example how a filter on the track collection could be built:


Each resource returned by the collection searches include a score attribute: ext:score="100" This is the score assigned by the Lucene search engine -- for more information on what this score entails, please see the [http://lucene.apache.org/java/3_1_0/scoring.html Lucene scoring documentation].
<pre>AND artistid AND releaseid AND ( title OR duration OR ... )
</pre>


All of the filter arguments passed into a collection search are joined using AND logic (this used to be OR logic, but was changed as of December 17th, 2006). Each new argument passed to the collection search is likely to constrict the hits returned -- this is what most people expect. If this logic does not suit you, please consider using the <code><nowiki>query</nowiki></code> argument to pass a raw lucene query to the collection search. This allows you to customize the query to your liking -- we suggest that you use the standard web interface to design and test your queries and then simply pass a customized query those to the collection searches.
If both <code><nowiki>artist</nowiki></code> and <code><nowiki>artistid</nowiki></code> are given, the <code><nowiki>artist</nowiki></code> parameter should be ignored (as with <code><nowiki>releaseid</nowiki></code> and <code><nowiki>release</nowiki></code>). The lucene query syntax is never used. That means, you can always put data read from file tags into your queries without having to escape special characters.

==Examples==

Below are a few user contributed examples to illustrate the use of this web service:


To get the Official XTC Releases that best match the release title "Wasp Star Apple Venus Volume 2", this would be the query: <code><nowiki>http://musicbrainz.org/ws/1/release/?type=xml&artist=XTC&releasetypes=Official&limit=10&title=Wasp+Star+Apple+Venus+Vol+2</nowiki></code>
=Discussion=


Tracks listing can then be gotten by choosing the release id and querying for tracks: <code><nowiki>http://musicbrainz.org/ws/1/release/6d931ac2-e389-4e99-8a01-1da65162c372?type=xml&inc=tracks</nowiki></code>
* When using <code><nowiki>?name=...</nowiki></code> it says it retrieves resources with a matching name (or title). What kind of "matching"?
* How exactly does <code><nowiki>?duration=...</nowiki></code> work - does it support range or fuzzy matching for example?
* If multiple filter arguments are given, how do they combine? Is it allowed to repeat a filter argument (e.g. <code><nowiki>?artist=X&artist=Y</nowiki></code>) ?
* AFAICT nowhere does it say what exactly all the <code><nowiki>?inc</nowiki></code> options do. I can guess most of them, in a vague sort of way, but for example is <code><nowiki>?inc=artist-rel</nowiki></code> artist releases or artist relationships (or something else)? If these have already been defined, then a pointer to that definition would be helpful.


[[Category:To Be Reviewed]] [[Category:Development]]
[[Category:Development]] [[Category:End_of_Life_Products]] [[Category:WikiDocs Page]]

Latest revision as of 05:43, 27 April 2020

Status: This web service is no longer in service! The current XML web service implementation is documented here.

Products > XML Web Service Version 1

Introduction

The web service discussed in this document is an interface to the MusicBrainz database which contains a huge amount of music metadata, all maintained by the MusicBrainz community. It is aimed at developers of media players, CD rippers, taggers and other applications requiring music metadata. The service's architecture follows the REST design principles. Interaction with the web service is done using HTTP and all content is served in a simple but flexible XML format.

This document first describes how the data in MusicBrainz is organized. Users who already have experience in using the website can safely skip this section and start with the specification sections.

The MusicBrainz Metadata Model

MusicBrainz uses an object oriented schema to model music metadata. The main classes are artist, release, track and label, each with a different set of attributes and relations. Apart from their traditional relations (artists have releases, releases contain tracks), a more powerful schema was introduced (sometimes called AdvancedRelationships).

It allows users to link an object of one class to an object of any other class (URLs are permitted, too). Many different link types exist (see AdvancedRelationshipType for a list), which can be used to specify the artist who did background vocals on a release or track, who is married to whom, where an artist's offical homepage is, and a lot more. Those links themselves may have attributes, with their semantics depending on the link type.

The following sections discuss the main classes in more detail.

The Artist Class

In MusicBrainz, artists always have a unique ID, a name and a sort name. If the artist name isn't unique, a disambiguation comment is used to provide more information about the artist. Additionally, an artist may also be flagged as Person or Group and it can have a begin date and an end date. For persons, these are the dates of birth and death, for groups they are the founding and dissolving dates.

An artist can have any number of releases and relations to other artists, releases, tracks and URLs.

The Release Group Class

A release group aggregates similar releases. All release groups have a unique ID, a title and one or more releases. Just like releases, release groups have a type ("Album", "Compilation", "Single" etc.).

The Release Class

All releases have a unique ID, a title and one or more tracks. Each release has a type ("Album", "Compilation", "Single" etc.), a status ("Official", "Promotion", "Bootleg") and language information. A release may also have additional release events, which are represented as a list of (country, date) tuples, sometimes called release information.

A common use case is to look up a release using a DiscID generated from an Audio CD's table of contents (TOC). A release can have any number of DiscIDs (including none), mostly due to different pressings. In rare cases, where two different CDs have the same TOC, a DiscID may map to more than one release.

Relations are used to link a release to other releases, artists, tracks and URLs.

The Track Class

Tracks have a unique ID, a title and one main artist. They may also have a duration attribute indicating the play time. There can be any number of PUIDs, which are used to lookup tracks. PUIDs are audio fingerprints generated from music files, but they are not unique, so a PUID can be associated with many tracks.

As with the other classes, a track object can have any number of relations to artists, releases, tracks and URLs.

The Label Class

In MusicBrainz, labels always have a unique ID and a name (they also used to have a sort name). If the label name isn't unique, a disambiguation comment is used to provide more information about the label. Additionally they may have a code, a country and founding and dissolving dates. Each label has also a type ("Distributor", "Holding", ...).

A label can have any number of releases and relations to other labels, artists, releases and URLs.

The URL Schema

All MusicBrainz objects (artists, release groups, releases, tracks and labels) are modeled as resources. Resources have unique URLs and can be accessed using standard HTTP. Each resource is also part of a collection. This is a special resource which represents all objects of a type.

For this version of the web service, the http://musicbrainz.org/ws/1/ namespace has been reserved. It is further structured like this:

http://musicbrainz.org/ws/1/artist/ Collection of all artists
http://musicbrainz.org/ws/1/artist/MBID An individual artist
http://musicbrainz.org/ws/1/release-group/ Collection of all release groups
http://musicbrainz.org/ws/1/release-group/MBID An individual release group
http://musicbrainz.org/ws/1/release/ Collection of all releases
http://musicbrainz.org/ws/1/release/MBID An individual release
http://musicbrainz.org/ws/1/track/ Collection of all tracks
http://musicbrainz.org/ws/1/track/MBID An individual track
http://musicbrainz.org/ws/1/label/ Collection of all labels
http://musicbrainz.org/ws/1/label/MBID An individual label
http://musicbrainz.org/ws/1/tag/ Folksonomy tags
http://musicbrainz.org/ws/1/rating/ Ratings

Basically, there are two different ways to access MusicBrainz data. If you know the MBID (a globally unique identifier assigned to each object in the database), you can request the resource directly. To access the artist "Tori Amos" for example, the resource http://musicbrainz.org/ws/1/artist/c0b2500e-0cef-4130-869d-732b23ed9df5?type=xml may be used.

Another option is to use the artist collection. Since this collection is huge, it is unfeasible to request all of it and then extract the data you need. Instead, collections support filters, which allow to limit the amount of data based on some criteria. For example, you can use a filter to only request artists with the name "Tori Amos": http://musicbrainz.org/ws/1/artist/?type=xml&name=Tori+Amos. The Filters supported depend on the collection and are described below. Data returned from collections will also have an ext:rating value="[rating]" attribute that indicates the rating returned from the search engine -- the rating value is between 0 and 100.

In REST, HTTP methods are used to create (POST), retrieve (GET), modify (PUT) and delete (DELETE) resources. The most important method for this web service is GET, which returns a representation for the requested resource. Several different representations are possible, but at this point only the XML format discussed later in this document is supported.

By default, the web service only returns a basic representation of a resource. Additional information can be requested using the inc parameter, which depends on the resource. If you want to request a release including all tracks and additional release events for example, you can use this URL: http://musicbrainz.org/ws/1/release/02232360-337e-4a3f-ad20-6cdd4c34288c?type=xml&inc=tracks+release-events

The following sections discuss the parameters available for each type of resource. The type parameter is required for all web service queries:

type Selects the representation of the resource. Currently only xml is supported. This is mandatory!

The inc parameter is only allowed for individual resources (but not for collections):

inc A list of space separated values describing how much detail should be included in the output. If there is no inc parameter, just the basic data for a resource is returned. For artists that would be name, sort-name, and disambiguation.

The limit, offset and query parameters are supported for all resource collections (but not for individual resources):

limit An integer value defining how many entries should be returned. Only values between 1 and 100 (both inclusive) are allowed. If not given, this defaults to 25.
offset Return search results starting at a given offset. Used for paging through more than one page of results.
query A lucene search query. If this is given, then all other collection/filter arguments are ignored, you need to use the field names as detailed in TextSearchSyntax

Note that multiple parameters with the same name are not permitted.

The following HTTP status codes are used:

code cause
200 OK Resource retrieved successfully.
400 Bad Request Syntactically invalid MBID requested.
Invalid parameter value (ie. invalid inc tag)
Missing required parameter value (ie. type not set)
401 Unauthorized Client requested a resource which requires authentication via HTTP Digest Authentication.
If sent even though user name and password were given: user name and/or password are incorrect.
404 Not Found Wrong web service prefix. /ws/ would be correct for the MusicBrainz server.
Invalid version number. Only version 1 is currently supported.
Invalid entity name. Only artist, release, track, or user are permitted.
Resource not found. There is no resource having this ID (maybe it was merged or deleted).

artist resources

Looking up a Specific Artist

Parameters for http://musicbrainz.org/ws/1/artist/MBID:

inc Supported: 'aliases', 'release-groups', 'sa-'*, 'va-'*, 'artist-rels', 'label-rels', 'release-rels', 'track-rels', 'url-rels', 'tags', 'ratings', 'user-tags', 'user-ratings', 'counts', 'release-events', 'discs', 'labels'

Example: http://musicbrainz.org/ws/1/artist/c0b2500e-0cef-4130-869d-732b23ed9df5?type=xml&inc=url-rels+artist-rels

Note:

When looking up a specific artist MBID, while any of the other inc parameters may be used in any combinations, only one of 'sa-' or 'va-' may be used in any given query.

Searching Artists

Parameters for http://musicbrainz.org/ws/1/artist/:

name Fetch a list of artists with a matching name
limit The maximum number of artists returned. Defaults to 25, the maximum allowed value is 100.

Example: http://musicbrainz.org/ws/1/artist/?type=xml&name=Tori+Amos

'sa-' and 'va-'

To get an artist's releases, the 'sa-' and 'va-' prefixes (for single artist and various artist releases, respectively) together with the desired release type have to be used. For example, the release tag sa-Album requests single artist releases, while va-Bootleg requests various artists bootlegs. Multiple tags may be used, so inc=sa-Compilation+sa-Official is valid and returns all official compilations by that artist (AND conjunctions are used for release types!).

release group resources

Looking up a Specific Release Group

Parameters for http://musicbrainz.org/ws/1/release-group/MBID:

inc Supported: 'artist', 'releases'

Searching Release Groups

Parameters for http://musicbrainz.org/ws/1/release-group/:

title Fetch a list of release groups with a matching title
artist The returned release groups should match the given artist name
artistid The returned release groups should match the given artist ID (36 character ASCII representation). If this is given, the artist parameter is ignored.
releasetypes The returned release groups must match all of the given release types. This is a list of space separated values like Official, Bootleg, Album, Compilation, etc.
limit The maximum number of release groups returned. Defaults to 25, the maximum allowed value is 100.

release resources

Looking up a Specific Release

Parameters for http://musicbrainz.org/ws/1/release/MBID:

inc Supported: 'artist', 'counts', 'release-events', 'discs', 'tracks', 'release-groups', 'artist-rels', 'label-rels', 'release-rels', 'track-rels', 'url-rels', 'track-level-rels', 'labels', 'tags', 'ratings', 'user-tags', 'user-ratings', 'isrcs'

Searching Releases

Parameters for http://musicbrainz.org/ws/1/release/:

title Fetch a list of releases with a matching title
discid Fetch all releases matching to the given DiscID
artist The returned releases should match the given artist name
artistid The returned releases should match the given artist ID (36 character ASCII representation). If this is given, the artist parameter is ignored.
releasetypes The returned releases must match all of the given release types. This is a list of space separated values like Official, Bootleg, Album, Compilation, etc.
count Number of tracks in the release
date Earliest release date for the release
asin The Amazon ASIN
lang The language for this release
script The script used this release
cdstubs Indicates whether to include CD stubs in the result or not. Can be set to "yes" or "no". By default CD stubs are included.
limit The maximum number of releases returned. Defaults to 25, the maximum allowed value is 100.

For the releasetypes parameter, the MusicBrainz release type and release status values are used (see ReleaseAttribute). Note that the current MusicBrainz server only supports one release type and one release status value, so for example releasetypes=Live+Compilation won't work because for releasetypes an AND conjunction is used.

Please note, that additional information like the track artist is only given once for a specific track/recording. If the same track/recording appears in another release in the results, no track artist will be given again. You can build a dictionary for the tracks, indexed by "track id" (which is a recording id actually) and check if information for a track was given earlier.

Submitting a CDStub

Parameters for posting to http://musicbrainz.org/ws/1/release/:

title Title of the release
discid DiscID of the release
toc TOC of the release
artist Artist of the release
client The ID of the client software submitting the CDStub. This has to be the application's name and version number, not that of a client library (client libraries should use HTTP's User-Agent header)! The required format: application-version, where version must not contain a - character.
barcode Barcode of the release (optional)
comment Comment for the release (optional)

For each track:

trackN Title of the Nth track in the release
artistN Artist of the Nth track in the release (for Various Artists release)

Example:

  • Single artist release: http://musicbrainz.org/ws/1/release/?client=<client>&title=<title>&artist=<sa-artist>&toc=<toc>&discid=<discid>&barcode=<barcode>&comment=<comment>&track0=<track0>&track1=<track1>...
  • Various artists release: http://musicbrainz.org/ws/1/release/?client=<client>&title=<title>&toc=<toc>&discid=<discid>&barcode=<barcode>&comment=<comment>&track0=<track0>&artist0=<artist0>&track1=<track1>&artist1=<artist1>...

track resources

Looking up a Specific Track

Parameters for http://musicbrainz.org/ws/1/track/MBID:

inc Supported: 'artist', 'releases', 'puids', 'artist-rels', 'label-rels', 'release-rels', 'track-rels', 'url-rels', 'tags', 'ratings', 'user-tags', 'user-ratings', 'isrcs'

Searching Tracks

Parameters for http://musicbrainz.org/ws/1/track/:

title Fetch a list of tracks with a matching title
artist The returned tracks have to match the given artist name.
release The returned tracks have to match the given release title.
duration The length of the track in milliseconds
tracknumber The track number
artistid The artist's MBID. If this is given, the artist parameter is ignored.
releaseid The release's MBID. If this is given, the release parameter is ignored.
puid The returned tracks have to match the given PUID. Note that when searching by this field, all other parameter values are ignored and cannot be used to further filter the results. PUID should be used on its own.
count Number of tracks on the release
releasetype The type of the release this track appears on
limit The maximum number of tracks returned. Defaults to 25, the maximum allowed value is 100.

PUID submission

PUID submission works using POST on the collection of tracks. The parameters are sent url-encoded, that means with a content type of application/x-www-form-urlencoded.

Parameters for posting to http://musicbrainz.org/ws/1/track/:

client The ID of the client software submitting the PUIDs. This has to be the application's name and version number, not that of a client library (client libraries should use HTTP's User-Agent header)! The required format: application-version, where version must not contain a - character.
puid A (TrackId, PUIDId) pair, separated by a single space character. Both TrackId and PUID are in their 36 character ASCII representation. This parameter may appear multiple times.

Please consider batching multiple PUID submissions into one web service call. Not only does this reduce the number of web service calls, it reduces the number of edits stored in the database.

Users have to be logged in to submit PUIDs. This is independent from the website login and works via HTTP Digest Authentication. The realm is 'musicbrainz.org'.

ISRC submission

ISRC submission works very similar to the PUID submission by using POST on the collection of tracks. The parameters are sent url-encoded, that means with a content type of application/x-www-form-urlencoded.

Parameters for posting to http://musicbrainz.org/ws/1/track/:

isrc A (TrackId, ISRC) pair, separated by a single space character. Both TrackId is in its 36 character ASCII representation and ISRC is ASCII formatted according to ISRC formatting rules. This parameter may appear multiple times.

Please batch multiple ISRC submissions into one web service call. Not only does this reduce the number of web service calls, it reduces the number of edits stored in the database.

Users have to be logged in to submit ISRCs. This is independent from the website login and works via HTTP Digest Authentication. The realm is 'musicbrainz.org'.

label resources

Looking up a Specific Label

Parameters for http://musicbrainz.org/ws/1/label/MBID:

inc Supported: 'aliases', 'artist-rels', 'label-rels', 'release-rels', 'track-rels', 'url-rels', 'tags', 'ratings', 'user-tags', 'user-ratings'

Searching Labels

Parameters for http://musicbrainz.org/ws/1/label/:

name Fetch a list of labels with a matching name
limit The maximum number of labels returned. Defaults to 25, the maximum allowed value is 100.

folksonomy resources

This requires you to be logged in and shown only your own tags. In order to see other tags use the other resources with the parameter inc=tags as described above.

Looking up tags for a Specific Entity

Parameters for http://musicbrainz.org/ws/1/tag/:

id The MBID of the entity that you would like to see your tags for, this could be a track ID, release ID, artist ID or label ID
entity Identifies the entity type, can be artist, release, track or label

Example: http://musicbrainz.org/ws/1/tag/?id=5fc9f3d4-8f61-4f35-a20a-f8a0cae84d46&type=xml&entity=artist (this will show an empty list of tags unless you have tagged this artist)

Tags submission

Folksonomy tag submission works using POST on the collection of tags. The parameters are sent url-encoded, that means with a content type of application/x-www-form-urlencoded.

Parameters for posting to http://musicbrainz.org/ws/1/tag/:

Simple submission

id The MBID of the entity you are adding tags to, this could be a track ID, release ID, artist ID or label ID
entity Identifies the entity type, can be artist, release, track or label
tags Comma separated list of tags to be added

Batch submission

You can tag up to 20 different entities at the same time.

For each entity, if entity is the Nth you're submitting:

id.N The MBID of the Nth entity you are adding tags to, this could be a track ID, release ID, artist ID or label ID
entity.N Identifies the Nth entity type, can be artist, release, track or label
tags.N Comma separated list of tags to be added

Example: http://musicbrainz.org/ws/1/tag/?entity.0=<entity-type>&id.0=<mbid>&tags.0=<tags>&entity.1=<entity-type>&id.1=<mbid>&tags.1=<tags>...

Users have to be logged in to submit tags. This is independent from the website login and works via HTTP Digest Authentication. The realm is 'musicbrainz.org'.

ratings resources

This requires you to be logged in and shown only your own ratings. In order to see other ratings use the other resources with the parameter inc=ratings as described above.

Looking up rating for a Specific Entity

Parameters for http://musicbrainz.org/ws/1/rating/:

id The MBID of the entity that you would like to see your rating for, this could be a track ID, release ID, artist ID or label ID
entity Identifies the entity type, can be artist, release, track or label

Example: http://musicbrainz.org/ws/1/rating/?id=5fc9f3d4-8f61-4f35-a20a-f8a0cae84d46&type=xml&entity=artist (this will show an empty rating unless you have rated this artist)

Ratings submission

Rating submission works using POST on the collection of ratings. The parameters are sent url-encoded, that means with a content type of application/x-www-form-urlencoded.

Parameters for posting to http://musicbrainz.org/ws/1/rating/:

Simple submission

id The MBID of the entity that you are rating, this could be a track ID, release ID, artist ID or label ID
entity Identifies the entity type, can be artist, release, track or label
rating Integer between 0 and 5 (actually 1-5 are ratings values, 0 is equivalent to unrating)

Batch submission

You can rate up to 20 different entities at the same time.

For each entity, if entity is the Nth you're submitting:

id.N The MBID of the Nth entity that you are rating, this could be a track ID, release ID, artist ID or label ID
entity.N Identifies the Nth entity type, can be artist, release, track or label
rating.N Integer between 0 and 5 (actually 1-5 are ratings values, 0 is equivalent to unrating)

Example: http://musicbrainz.org/ws/1/rating/?entity.0=<entity-type>&id.0=<mbid>&rating.0=<rating>&entity.1=<entity-type>&id.1=<mbid>&rating.1=<rating>...

Users have to be logged in to submit ratings. This is independent from the website login and works via HTTP Digest Authentication. The realm is 'musicbrainz.org'.

user collection resources

User collections are different from collections that contain artists, releases, tracks and labels. User collections refer to the MusicBrainz feature that allows users to store information about their personal music collections. Using the user collections resource you can add/removes releases or list your music collection.

You can only remove or add releases in one call, you cannot do both in one call.

NOTES: Using a GET was previously possible for adding and removing releases. This has been disallowed and future releases of the web service will not allow these operations with a GET method. If you have an existing application that uses a GET, please change it as soon as possible.

Adding releases

Parameters for http://musicbrainz.org/ws/1/collection/:

add A list of Releases MBIDs you'd like to add to your collection, separated by commas.

Example: http://musicbrainz.org/ws/1/collection/?add=cac64a87-42f9-4c1c-a5ef-1e6824e20678,cac64a87-42f9-4c1c-a5ef-1e6824e20678,cac64a87-42f9-4c1c-a5ef-1e6824e20678

Removing releases

Parameters for http://musicbrainz.org/ws/1/collection/:

remove A list of Releases MBIDs you'd like to remove from your collection, separated by commas.

Example: http://musicbrainz.org/ws/1/collection/?remove=cac64a87-42f9-4c1c-a5ef-1e6824e20678,cac64a87-42f9-4c1c-a5ef-1e6824e20678,cac64a87-42f9-4c1c-a5ef-1e6824e20678

List releases in collection

A list of albums in a users collection is returned from the collection resource when no arguments are supplied:

http://musicbrainz.org/ws/1/collection/ returns xml shown in the next section.

A maximum of 100 items will be returned for any one call to the collection resource. In order to fetch more than 100 items, please use the offset and maxitems parameters:

offset The offset into the collection where to return releases from.
maxitems The maximum number of items to return. This cannot be more than 100.

XML response

The XML response for all of the three collection actions is shown below. For a add/remove operation only the MBIDs of added/removed releases will be returned. When no action is given (list), all releases in the collection will be returned. 

<?xml version="1.0" encoding="UTF-8"?> 
  <metadata xmlns="http://musicbrainz.org/ns/mmd-1.0#">
    <release-list count="3">
      <release id="cac64a87-42f9-4c1c-a5ef-1e6824e20678"/>
      <release id="b71926ec-5813-4fa4-9372-0c07154a07af"/>
      <release id="172ddda3-1837-4fd2-8d12-ddd1e70b4c57"/>
    </release-list>
</metadata>

For listing the collection, the count attribute in the release-list element indicates the total number of releases in the collection.

The Resource Representation

As mentioned above, the type parameter selects the representation of the returned resources. At this point, the only available representation is xml. All returned data is in a newly developed XML-based language, the MusicBrainz XML Metadata Format.

Limiting Connections to the MusicBrainz Web Service

All users of the XML web service must ensure that each of their client applications never make more than ONE web service call per second. Making more than one call per second drives up the load on the servers and prevents others from using MusicBrainz. If you impact the server by making more than one call per second, your IP address may be blocked preventing all further access to MusicBrainz. For more details on this, please see our rate limiting page.

Identifying your application to the MusicBrainz Web Service

It is important that your application set a proper User-Agent string in its HTTP request headers. Please read our rate limiting documentation for more details.

A Note to Application Developers

The PythonMusicBrainz2 package is the reference implementation of a client library for this web service. It has been designed to be as simple to use as possible but still provides access to all parts of the service. If you are planning to write bindings for another programming language, you are encouraged to follow the programming model, object oriented schema, and terminology of PythonMusicBrainz2 as far as it makes sense for your language.

List of known implementations:

Please don't start new development using these libraries. There are libraries available for the current web service.


Development Notes

The following sections are informal. They are not part of the specification.

Use Cases

This new web service will have the following use cases:

  • Retrieve artist (via mbid)/release (via mbid/cdid)/track (via mbid)
    • Each of these should return a minimal amount of data and have options to return more detailed data:
      • artist: optional list of releases
      • release: optional artist info, cdids, release events, list of tracks
      • track: optional artist info
  • Retrieve a list of tracks that match a given PUID
    • same arguments that apply to track info should be used here
  • Full text search of the DB (via lucene query)
  • Login to MB
  • Submit PUIDs (after login)
  • Check donation status of user (for showing pop-ups in Picard)
  • Lookup track (like MBQ_FileLookup)

Collection filtering notes

Resource collections are not handled by the database, but by our Lucene search engine. This means that the data returned by collection queries may not be fully up to date, as the search indexes get computed once a day.

Each resource returned by the collection searches include a score attribute: ext:score="100" This is the score assigned by the Lucene search engine -- for more information on what this score entails, please see the Lucene scoring documentation.

All of the filter arguments passed into a collection search are joined using AND logic (this used to be OR logic, but was changed as of December 17th, 2006). Each new argument passed to the collection search is likely to constrict the hits returned -- this is what most people expect. If this logic does not suit you, please consider using the query argument to pass a raw lucene query to the collection search. This allows you to customize the query to your liking -- we suggest that you use the standard web interface to design and test your queries and then simply pass a customized query those to the collection searches.

Examples

Below are a few user contributed examples to illustrate the use of this web service:

To get the Official XTC Releases that best match the release title "Wasp Star Apple Venus Volume 2", this would be the query: http://musicbrainz.org/ws/1/release/?type=xml&artist=XTC&releasetypes=Official&limit=10&title=Wasp+Star+Apple+Venus+Vol+2

Tracks listing can then be gotten by choosing the release id and querying for tracks: http://musicbrainz.org/ws/1/release/6d931ac2-e389-4e99-8a01-1da65162c372?type=xml&inc=tracks

Retrieved from "https://wiki.musicbrainz.org/index.php?title=History:Development/XML_Web_Service/Version_1&oldid=74163"