MusicBrainz API/XML: Difference between revisions

From MusicBrainz Wiki
Jump to navigationJump to search
(→‎inc=: url browse incs)
(Redirected page to MusicBrainz API)
Tag: New redirect
 
(26 intermediate revisions by 10 users not shown)
Line 1: Line 1:
#REDIRECT [[MusicBrainz API]]
<small>[[Products]] > XML Web Service Version 2</small>

The web service discussed in this document is an interface to the [[MusicBrainz Database]]. 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.
The same web service is also available in [[Development/JSON_Web_Service|JSON format]].

The web service root URL is <code><nowiki>http://musicbrainz.org/ws/2/</nowiki></code>.

This page documents version 2 of our XML web service. Version 1 has been deprecated, but its documentation [[XML_Web_Service/Version_1|can still be referenced]]. [[Live_Data_Feed|Non-commercial]] use of this web service is free; please see [https://metabrainz.org/supporters/account-type our commercial plans] or [[Contact_Us|contact us]] if you would like to use this service commercially.

==Introduction==

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

area, artist, event, instrument, label, recording, release, release-group, series, work, url

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:

discid, 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>

... except that search is not implemented for URL entities at this time.

Of these:

* Lookups, Non-MBID lookups and Browse requests are documented in following sections.

==Searches==
Searches are documented at [[/Search|Web Service Search]].

==Relax NG Schema==

The file [https://github.com/metabrainz/mmd-schema/blob/master/schema/musicbrainz_mmd-2.0.rng musicbrainz_mmd-2.0.rng] is a Relax NG Schema for this web service. It can also be used to validate [[#Submitting data|submissions]] you're trying to make through it.

==Lookups==

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

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

Note that unless you have provided an MBID in exactly the format listed, you are not performing a lookup request. If your URL includes something like artist=<MBID>, then please see the [[#Browse|Browse]] section. If it includes query=<QUERY>, please see the [[/Search|Web Service Search]] page.

===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/area
/ws/2/artist recordings, releases, release-groups, works
/ws/2/event
/ws/2/instrument
/ws/2/label releases
/ws/2/recording artists, releases
/ws/2/release artists, collections, labels, recordings, release-groups
/ws/2/release-group artists, releases
/ws/2/work
/ws/2/url

In addition, [[#Relationships|Relationships]] are available for all entity types via inc parameters.

To include more than one subquery in a single request, separate the arguments to <code>inc=</code> with a + (plus sign), like <code>inc=recordings+labels</code>.

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.

Linked entities are always ordered alphabetically by gid.

=== 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 and its format.
- 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, area or work aliases; treat these as a set, as they are not deliberately ordered
- annotation include annotation
- 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 ===

- area-rels
- artist-rels
- event-rels
- instrument-rels
- label-rels
- place-rels
- recording-rels
- release-rels
- release-group-rels
- series-rels
- url-rels
- work-rels

By default, these 'inc=' arguments will only load relationship for the requested entity. When you are loading a release, you might want to load relationships for all its recordings and also works linked to the recordings. This is useful to get full release credits. There are additional arguments that can be used only on release requests and allow you to specify for which entities to load relationships:

- recording-level-rels
- work-level-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: /discid/<discid>?inc=<INC>&toc=<TOC>

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

If there are no matching releases in MusicBrainz, but a matching [[CD Stub|CDStub]] exists, it will be returned. This is the default behaviour. If you do ''not'' want to see CD stubs, pass 'cdstubs=no.' CD stubs are contained within a <cdstub> element, and otherwise have the same form as a release. Note that CD stubs do not have artist credits, just artists.

If you provide the "toc" query parameter, and if the provided discid is not known by MusicBrainz, a fuzzy lookup will done to find matching MusicBrainz releases. Note that if CD stubs are found this will not happen. If you do want TOC fuzzy lookup, but not cdstub searching, specify "cdstubs=no". For example:

/ws/2/discid/I5l9cCSFccLKFEKS.7wqSZAorPU-?toc=1+12+267257+150+22767+41887+58317+72102+91375+104652+115380+132165+143932+159870+174597

Will look for the disc id first, and if it fails, will try to find tracklists that are within a similar distance to the one provided.

It's also possible to perform a fuzzy toc search without a discid. Passing "-" (or any invalid placeholder) as the discid will cause it to be ignored if a valid toc is present:

/ws/2/discid/-?toc=1+12+267257+150+22767+41887+58317+72102+91375+104652+115380+132165+143932+159870+174597

By default, fuzzy toc searches only return mediums whose format is set to "CD." If you want to search all mediums regardless of format, add 'media-format=all' to the query:

/ws/2/discid/-?toc=1+12+267257+150+22767+41887+58317+72102+91375+104652+115380+132165+143932+159870+174597&media-format=all

The toc consists of the following:
* First track (always 1)
* total number of tracks
* sector offset of the leadout (end of the disc
* a list of sector offsets for each track, beginning with track 1 (generally 150 sectors)

=== isrc ===

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

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.

Browsed entities are always ordered alphabetically by gid. If you need to sort the entities, you will have to fetch all entities (see "Paging" below) and sort them yourself.

===Linked entities===

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

/ws/2/area (none)
/ws/2/artist area, recording, release, release-group, work
/ws/2/event area, artist, place
/ws/2/label area, release
/ws/2/place area
/ws/2/recording artist, release
/ws/2/release area, artist, label, track, track_artist, recording, release-group
/ws/2/release-group artist, release
/ws/2/work artist
/ws/2/url resource

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>).

The URL endpoint's 'resource' entity is for providing a URL directly, rather than a URL MBID, for example https://musicbrainz.org/ws/2/url?resource=http://www.madonna.com/ versus https://musicbrainz.org/ws/2/url/b663423b-9b54-4067-9674-fffaecf68851. This URL will need to be appropriately URL-escaped for inclusion as a query parameter; this means that URLs that include url-escaped parameters, or query parameters of their own, will need to be escaped a second time.

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

===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/area aliases
/ws/2/artist aliases
/ws/2/event aliases
/ws/2/instrument aliases
/ws/2/label aliases
/ws/2/place aliases
/ws/2/recording artist-credits, isrcs
/ws/2/release artist-credits, labels, recordings, release-groups, media, discids, isrcs (with recordings)
/ws/2/release-group artist-credits
/ws/2/work aliases
/ws/2/area aliases
/ws/2/url (only relation includes)

In addition to the inc= values listed above, all entities support:

annotation

All entities except release support:

tags, user-tags

All entities except release and place support:

ratings, user-ratings

In addition, [[#Relationships|Relationships]] are available for all entity types via inc parameters, as with lookup requests.

== Release Type and Status ==

Any query which includes release-groups in the results can be filtered to only include release groups of a certain type. Any query which includes releases in the results can be filtered to only include releases of a certain type and/or 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 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 "musicbrainz.org".

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 Data ===

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.

An example request is reproduced below:

<pre>
<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>
</pre>

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 [[/examples|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.

An example request is reproduced below:

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

==== collections ====

To add and remove release from your collection perform a PUT and DELETE requests to /ws/2/collection/releases, respectively. For example:

PUT /ws/2/collection/f4784850-3844-11e0-9e42-0800200c9a66/releases/455641ea-fff4-49f6-8fb4-49f961d8f1ad;c410a773-c6eb-4bc0-9df8-042fe6645c63?client=example.app-0.4.7
DELETE /ws/2/collection/f4784850-3844-11e0-9e42-0800200c9a66/releases/455641ea-fff4-49f6-8fb4-49f961d8f1ad;?client=example.app-0.4.7

You may submit up to ~400 releases in a single request, separated by a semicolon (;), as the PUT example above shows. You are restricted to a maximum URI length of 16kb at the moment (which roughly equates to 400 release gids)

To get the contents of a collection, simply send a GET request to the releases resource:

GET /ws/2/collection/f4784850-3844-11e0-9e42-0800200c9a66/releases

You can also perform a get request on the collection list, which will present you a list of collections for the currently authenticated user, with the amount of releases in each collection:

GET /ws/2/collection


=== Barcode submission ===

Barcodes may be associated with releases by issuing an XML POST request to:

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

The body of the request must be an XML document with a list of <releases>s in a <release-list>, and a single barcode in a <barcode> element for each release. For example:

<pre>
<metadata xmlns="http://musicbrainz.org/ns/mmd-2.0#">
<release-list>
<release id="047ea202-b98d-46ae-97f7-0180a20ee5cf">
<barcode>9780262560933</barcode>
</release>
</release-list>
</metadata>
</pre>

Upon issuing this request MusicBrainz will create a single edit in the edit queue for applying these changes. These changes will ''not'' be automatically applied, though they will be applied if either no one votes against your changes, or your changes expire (this edit is applied on expiration).

=== ISRC submission ===

ISRCs may be associated with recordings by issuing an XML POST request to:

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

The body of the request must be an XML document with a list of <recording>s in a <recording-list>, and a list of <ISRC>s in a <isrc-list> to be associated with the recordings. For example:

<pre>
<metadata xmlns="http://musicbrainz.org/ns/mmd-2.0#">
<recording-list>
<recording id="b9991644-7275-44db-bc43-fff6c6b4ce69">
<isrc-list count="1">
<isrc id="JPB600601201" />
</isrc-list>
</recording>
<recording id="75c961c9-6e00-4861-9c9d-e6ca90d57342">
<isrc-list count="1">
<isrc id="JPB600523201" />
</isrc-list>
</recording>
</recording-list>
</metadata>
</pre>

Example code which illustrates this process can be found in our subversion repository: [http://svn.musicbrainz.org/miscellaneous/trunk/isrcsubmit-python/ isrcsubmit-python].

==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 [[XML_Web_Service/Rate_Limiting|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 [[XML_Web_Service/Rate_Limiting|rate limiting]] documentation for more details.

==Libraries to use the Web Service==

The Web Service can be accessed with [[libmusicbrainz]].

===3rd party libraries===

* Python: [http://python-musicbrainzngs.readthedocs.org/ python-musicbrainzngs] Python2/3 bindings
* Java: [http://code.google.com/p/musicbrainzws2-java/ musicbrainzws2-java]
* Ruby:
** [https://github.com/dwo/musicbrainz-ruby musicbrainz-ruby]
** [https://github.com/magnolia-fan/musicbrainz magnolia-fan/musicbrainz] ruby 1.9+
* PHP: [https://github.com/mikealmond/MusicBrainz mikealmond/MusicBrainz], a fork of [[phpbrainz]]
* C#: [https://github.com/avatar29A/MusicBrainz avatar29A/MusicBrainz]
* Objective-C: [https://github.com/demosdemon/libmusicbrainz-objc libmusicbrainz-objc]
* Haskell:
** [http://hackage.haskell.org/package/MusicBrainz Clint Adams' bindings (hackage)]
** [https://github.com/ocharles/haskell-musicbrainz-ws2 haskell-musicbrainz-ws2 (ocharles)]
* common lisp: [https://github.com/0/cl-musicbrainz cl-musicbrainz]
* Perl: [https://github.com/mavit/webservice-musicbrainz/tree/ws2 Work in progress]. Patches welcome!

[[Category:Development]] [[Category:Products]] [[Category:WikiDocs Page]]

Latest revision as of 20:10, 10 July 2020

Redirect to: