Development/XML Web Service/Version 1

From MusicBrainz Wiki
Jump to: navigation, search
Status: This web service has been deprecated! The current XML web service implementation is documented here.

Products > XML Web Service Version 1

Contents

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, a name and 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

Personal tools