Difference between revisions of "MusicBrainz API/XML"

From MusicBrainz Wiki
(Undo revision 40752 by 80.101.192.137 (Talk))
(Redirected page to MusicBrainz API)
(Tag: New redirect)
 
(149 intermediate revisions by 38 users not shown)
Line 1: Line 1:
=XML Web Service v2=
+
#REDIRECT [[MusicBrainz API]]
 
 
This is my proposal on how V2 of the [[XML_Web_Service]] should work. --warp.
 
 
 
==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/release-group    artist, releases
 
  /ws/2/work              artist
 
  /ws/2/recording        artist, releases
 
  /ws/2/release          artist, label, recordings, release-groups
 
 
 
All lookups which include 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
 
  - 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).
 
 
 
As a special case, artists will be included for recordings on a /ws/2/release?inc=artist+recordings lookup.
 
 
 
=== Misc inc= arguments ===
 
 
 
  - aliases          include artist, label or work aliases
 
 
 
=== 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/release-group    artist, release
 
  /ws/2/work              artist
 
  /ws/2/recording        artist, release
 
  /ws/2/release          artist, label, recording, release-group
 
 
 
As a special case, release also allows track_artist, which is intended to allow you to browse various artist appearances for an artist.  It will return any release where the artist appears in the artist_credit for a track, but NOT in the artist_credit for the entire release (as those would already have been returned in a request with artist=<MBID>).
 
 
 
: <span style="color:#888">〜 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.</span>
 
 
 
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/release-group    artist
 
  /ws/2/work              artist, aliases
 
  /ws/2/recording        artist
 
  /ws/2/release          artist, label
 
 
 
: <span style="color:#888">〜 murdos added work aliases here, but I don't see these in the database, what am I missing? --warp.</span>
 
:: <span style="color:#888">〜 warp should update his database. He is missing [http://git.musicbrainz.org/gitweb/?p=musicbrainz-server/core.git;a=blob;f=admin/sql/CreateTables.sql;h=57cca0fb74bf0261427989454124b788af365351;hb=HEAD#l886 this code in master] ([http://codereview.musicbrainz.org/r/641/ code review], [http://jira.musicbrainz.org/browse/MBS-607 jira ticket]) --murdos.</span>
 
::: <span style="color:#888">〜 thanks murdos :). --warp.</span>
 
 
 
In addition to the inc= values listed above, all entities (except release) support:
 
 
 
  tags, ratings, user-tags, user-ratings
 
 
 
: <span style="color:#888">〜 we probably want to allow a few more inc= arguments here, though we can always add more later. --warp.</span>
 
 
 
== 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
 

Latest revision as of 20:10, 10 July 2020

Redirect to: