MusicBrainz API/XML

From MusicBrainz Wiki
Jump to navigationJump to search

XML Web Service v2

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

NOTE: As of the beta 2 release on 2010-06-21, most of what is documented below has been implemented. Currently missing are the filters on release-group type and release status, if you want to know when this gets added, keep an eye on http://jira.musicbrainz.org/browse/MBS-686 . POST requests also haven't been implemented, and haven't been documented here. The ticket for those is http://jira.musicbrainz.org/browse/MBS-142 .

Introduction

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

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

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

 rating, tag, collection

And we allow you to perform lookups based on other unique identifiers with these resources:

 disc, puid, isrc, iswc

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

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

Of these:

  • Lookups, Non-MBID lookups and Browse requests are documented in following sections.
  • Searches are implemented by the search server and are documented at Next_Generation_Schema/SearchServerXML.
  • ratings, tags and collections are not currently documented for /ws/2.

Lookups

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

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

Subqueries

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

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

All lookups which include release-groups allow a type= argument to narrow down the release-groups. All lookups which include releases also allow the type= argument, and a status= argument is allowed.

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

inc= arguments which affect subqueries

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

 - discids           include discids for all media in the releases
 - media             include media for all releases, this includes the # of tracks on each medium.
 - puids             include puids for all recordings
 - isrcs             include isrcs for all recordings
 - artist-credits    include artists credits for all releases and recordings
 - various-artists   include only those releases where the artist appears on one of the tracks, 
                     but not in the artist credit for the release itself (this is only valid on a
                     /ws/2/artist?inc=releases request).

Misc inc= arguments

 - aliases                   include artist, label or work aliases
 - tags, ratings             include tags and/or ratings for the entity
 - user-tags, user-ratings   same as above, but only return the tags and/or ratings submitted by the specified user

Requests with user-tags or user-ratings require authentication. You can authenticate using HTTP Digest, use the same username and password used to access the main http://musicbrainz.org website.

Relationships

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

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

Non-MBID Lookups

Instead of MBIDs, you can also perform lookups using several other unique identifiers. However, because clashes sometimes occur, each of these lookups return a list of entities (there is no limit, all linked entities will be returned, paging is not supported).

discid

 lookup: /disc/<discid>?inc=<INC>

A discid lookup returns a list of associated releases, the 'inc=' arguments supported are identical to a lookup request for a release.

puid, isrc

 lookup: /puid/<puid>?inc=<INC>
 lookup: /isrc/<isrc>?inc=<INC>

puid and isrc lookups return a list of recordings, the 'inc=' arguments supported are identical to a lookup request for a recording.

iswc

 lookup: /iswc/<iswc>?inc=<INC>

An iswc lookup returns a list of works, the 'inc=' arguments supported are identical to a lookup request for a work.

Browse

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

 /ws/2/release?label=47e718e1-7ee4-460c-b1cc-1192a841c6e5

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

Linked entities

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

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

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

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

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

 /ws/2/release?artist=65f4f0c5-ef9e-490c-aee3-909e7ae6b2ab&status=bootleg&type=live

Or all albums and EPs by Autechre:

 /ws/2/release-group?artist=410c9baf-5469-44f6-9852-826524b80c61&type=album|ep

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

Paging

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

inc=

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

 /ws/2/artist            aliases
 /ws/2/label             aliases
 /ws/2/recording         artist-credits
 /ws/2/release           artist-credits, labels
 /ws/2/release-group     artist-credits
 /ws/2/work              artist-credits, aliases

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

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

Release Type and Status

Certain lookup and browse requests allow you to filter the returned releases on release group type and release status. Valid values are:

 status     official, promotion, bootleg, pseudo-release
 type       nat, album, single, ep, compilation, soundtrack, spokenword, interview, audiobook, live, remix, other


Submitting data

You can use the web service to submit certain kinds of data. Currently tags, ratings, PUIDs and ISRCs can be entered through the web service.

Authentication

All POST requests require authentication. You should authenticate using HTTP Digest, use the same username and password you use to access the main http://musicbrainz.org website. The realm is "webservice".

POST requests should always include a 'client' parameter in the URL (not the body). The value of 'client' should be the ID of the client software submitting data. 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 recommended format is "application-version", where version does not contain a - character.

User Tags and Ratings

You can submit tags and ratings through the web service using POST requests. As described above, client software needs to identify itself using the 'client=' parameter. In the following examples I will use 'example.app-0.4.7' as the client identifier, this is obviously a fictitious client.

tags

To submit tags, perform a POST request to the /ws/2/tag url, like this:

  /ws/2/tag?client=example.app-0.4.7

The body of your request should be an XML formatted list of entities with <user-tag> elements. You can validate your XML request against our schema (http://svn.musicbrainz.org/mmd-schema/trunk/schema/musicbrainz_mmd-2.0.rng).

An example request is reproduced below:

<metadata xmlns="http://musicbrainz.org/ns/mmd-2.0#">
    <artist-list>
        <artist id="a16d1433-ba89-4f72-a47b-a370add0bb56">
            <user-tag-list>
                <user-tag><name>female</name></user-tag>
                <user-tag><name>korean</name></user-tag>
                <user-tag><name>jpop</name></user-tag>
            </user-tag-list>
        </artist>
    </artist-list>
    <recording-list>
        <recording id="047ea202-b98d-46ae-97f7-0180a20ee5cf">
            <user-tag-list>
                <user-tag><name>noise</name></user-tag>
            </user-tag-list>
        </recording>
    </recording-list>
</metadata>

Because you're sending XML in the body of your POST request, make sure to also set the Content-Type to "application/xml; charset=utf-8".

For examples, see User:kuno/ws/2/examples.

ratings

To submit ratings, perform a POST request to the /ws/2/rating url, like this:

  /ws/2/rating?client=example.app-0.4.7

The body of your request should be an XML formatted list of entities with <user-rating> elements. You can validate your XML request against our schema (http://svn.musicbrainz.org/mmd-schema/trunk/schema/musicbrainz_mmd-2.0.rng).

An example request is reproduced below:

NOTE: the following is WRONG. should only accept entity-lists in the POST request body. will update soon. --warp.

<metadata xmlns="http://musicbrainz.org/ns/mmd-2.0#">
    <artist id="455641ea-fff4-49f6-8fb4-49f961d8f1ac">
        <user-rating>100</user-rating>
    </artist>
    <recording id="c410a773-c6eb-4bc0-9df8-042fe6645c62">
        <user-rating>20</user-rating>
    </recording>
</metadata>

PUID submission

[FIXME: write this bit --warp]

ISRC submission

[FIXME: write this bit --warp]