MusicBrainz API/Search

From MusicBrainz Wiki
< MusicBrainz API
Revision as of 20:49, 10 December 2011 by Ijabz (talk | contribs) (New page: This is the output currently returned from the Search Server, this has to match the 2.0 schema. Note this is NOT the webservice but is used by the webservice to perform searches, and is al...)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

This is the output currently returned from the Search Server, this has to match the 2.0 schema. Note this is NOT the webservice but is used by the webservice to perform searches, and is also used by the Web Interface to perform searches. The webservice will return the xml exactly as shown on this page, the webpage will receive a JSON'd version of the XML which it will render as Html.

Some of these entities are currently only returned by the webpage and not the web service, these are annotation, tags, cdstubs and freedb. But it is expected that at least annotations and tags will be added to the web service in future.

This sections lists the parameters common to all resource.

type Selects the index to be searched, artist, release, release-group, recording, work, label (track is supported but maps to recording)
format Selects the representation of the resource. Defaults to xml, but can also be json (for parsing to html)
query Lucene search query, this is mandatory
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.
version MMD version, defaults to 2, can be set to 1 for backwards compatibility.


The query field supports the full Lucene Search syntax, more details at http://lucene.apache.org/java/3_4_0/queryparsersyntax.html

When searching fields that come from a defined set of possible values such as country and gender find matches where these fields have not been set by searchng for unknown.

Example: http://musicbrainz.org/ws/2/release/?query=country:unknown


Artist

The artist index contains the following fields you can search:

field Description
alias the aliases/misspellings/artist credits for this artist
arid artist id
artist artist name
begin artist birth date/band founding date (format: YYYY-MM-DD)
comment artist comment to differentiate similar artists
country country associated with artist
end artist death date/band dissolution date (format: YYYY-MM-DD)
gender gender of artist
ipi artist ipi code
sortname artist sortname
tag folksonomy tag
type artist type (person or group)

Artist search terms with no fields specified search the artist, sortname and alias fields.

Example: http://www.musicbrainz.org/ws/2/artist/?query=artist:fred

Xml

<metadata xmlns="http://musicbrainz.org/ns/mmd-2.0#" xmlns:ext="http://musicbrainz.org/ns/ext#-2.0">
    <artist-list offset="0" count="1">
        <artist type="group" id="8538e728-ca0b-4321-b7e5-cff6565dd4c0" ext:score="100" >
            <name>Depeche Mode</name>
            <sort-name>Depeche Mode</sort-name>
            <life-span>
                <begin>1980</begin>
            </life-span>
            <alias-list>
                <alias>Depech Mode</alias>
            </alias-list>
        </artist>
    </artist-list>
</metadata>

Json

{"artist-list":{"offset":0,"count":1,"artist":[{"type":"group","id":"8538e728-ca0b-4321-b7e5-cff6565dd4c0","score":"100",
"name":"Depeche Mode","sort-name":"Depeche Mode","life-span":{"begin":"1980"},"alias-list":{"alias":["Depech Mode"]}}]}}

Release Group

The release group index contains these fields you can search:

field Description
arid artist id
artist complete artist name(s) as it appears on the release group
artistname an artist on the release group, each added as a separate field
comment disambuguation comment
creditname name credit on the release group, each added as a separate field
reid release id of release that is part of this release group
releasegroup name of release group
release name of release that is part of this release group
releases number of releases in this release group
rgid release group id
tag folksonomy tag
type release group type (e.g album)

Release group search terms with no fields search the releasegroup field only.

Example: http://www.musicbrainz.org/ws/2/release-group/?query=release:fred


Xml

<metadata xmlns="http://musicbrainz.org/ns/mmd-2.0#" xmlns:ext="http://musicbrainz.org/ns/ext#-2.0">
    <release-group-list offset="0" count="2">
        <release-group type="compilation" id="765675cc-070b-36e0-829c-69c7634e92ff" ext:score="100">
            <title>The History of John Fred and the Playboys</title>
            <artist-credit>
                <name-credit>
                   <artist id="05cfb5c7-0152-41f4-a9c9-622e8f710dfa">
                      <name>John Fred & His Playboy Band</name>
                      <sort-name>Fred, John & His Playboy Band</sort-name></artist>
                </name-credit>
            </artist-credit>
            <release-list count="1>
                <release id="9cddae0c-1764-41d2-a1c4-0af2a8404e57">
                   <title>The History of John Fred and the Playboys</title>
                </release>
            </release-list>
        </release-group>
        <release-group type="live" id="9856e177-6a63-3141-96da-00b80d08c66e" ext:score="100" xmlns:ext="http://musicbrainz.org/ns/ext#-2.0">
            <title>An Evening With John Kander & Fred Ebb</title>
            <artist-credit>
                <name-credit>
                    <artist id="0f1d3e45-b3a4-4a93-b29b-06ee9c6e94a8"><name>John Kander & Fred Ebb</name><sort-name>Kander, John & Ebb, Fred</sort-name></artist>
                </name-credit>
            </artist-credit>
            <release-list count="1>
                <release id="a204adf8-2bc7-46cf-b4af-b773bf803a89">
                   <title>An Evening With John Kander & Fred Ebb</title>
                </release>
            </release-list>
        </release-group>
    </release-group-list>
</metadata>

Json

{"release-group-list":{"offset":0,"count":1,"release-group":[{"type":["compilation"],"id":"765675cc-070b-36e0-829c-69c7634e92ff","score":"100","title"
:"The History of John Fred and the Playboys","artist-credit":{"name-credit":[{"artist":{"id":"05cfb5c7-0152-41f4-a9c9-622e8f710dfa","name":
"John Fred & His Playboy Band","sort-name":"Fred, John & His Playboy Band"}}]},"release-list":{"count":1,"release":[{"id":"9cddae0c-1764-41d2-a1c4-0af2a8404e57",
"title":"The History of John Fred and the Playboys"}]}}]}}

Release

The release index contains these fields you can search:

field Description
arid artist id
artist complete artist name(s) as it appears on the release
artistname an artist on the release, each artist added as a seperate field
asin the Amazon ASIN for this release
barcode The barcode of this release
catno The catalog number for this release, can have multiples when major using an imprint
comment Disambiguation comment
country The two letter country code for the release country
creditname name credit on the release, each artist added as a seperate field
date The release date (format: YYYY-MM-DD)
discids total number of cd ids over all mediums for the release
discidsmedium number of cd ids for the release on a medium in the release
format release format
label The name of the label for this release, can have multiples when major using an imprint
lang The language for this release. Use the three character ISO 639 codes to search for a specific language. (e.g. lang:eng)
mediums number of mediums in the release
puid The release contains recordings with these puids
reid release id
release release name
rgid release group id
script The 4 character script code (e.g. latn) used for this release
status release status (e.g official)
tracks total number of tracks over all mediums on the release
tracksmedium number of tracks on a medium in the release
type release group type (e.g album)

Release search terms with no fields search the release field only.

Example: http://www.musicbrainz.org/ws/2/release/?query=release:Schneider

Xml

<metadata xmlns="http://musicbrainz.org/ns/mmd-2.0#" xmlns:ext="http://musicbrainz.org/ns/ext#-2.0">
    <release-list offset="0" count="1">
        <release id="9ab1b03e-6722-4ab8-bc7f-a8722f0d34c1" ext:score="100">
            <title>Fred Schneider & The Shake Society</title>
            <status>official</status>
            <text-representation>
                <language>eng</language>
                <script>latn</script>
            </text-representation>
            <artist-credit>
                <name-credit>
                    <artist id="43bcca8b-9edc-4997-8343-122350e790bf">
                       <name>Fred Schneider</name>
                       <sort-name>Schneider, Fred</sort-name>
                    </artist>
                </name-credit>
            </artist-credit>
            <release-group type="Album"/>
            <date>1991-04-30</date>
            <country>us</country>
            <barcode>075992659222</barcode>
            <asin>075992659222</asin>
            <label-info-list>
                <label-info>
                    <catalog-number>9 26592-2</catalog-number>
                    <label>
                        <name>Reprise Records</name>
                    </label>
                </label-info>
            </label-info-list>
            <medium-list>
                <medium><format>cd</format>
                    <disc-list count="2"/>
                    <track-list count="9"/>
                 </medium>
            </medium-list>
        </release>
    </release-list>
</metadata>

Json

{"release-list":{"offset":0,"count":1,"release":[{"id":"9ab1b03e-6722-4ab8-bc7f-a8722f0d34c1","score":"100","title":"Fred Schneider & The Shake Society","status":"official",
"text-representation":{"language":"eng","script":"latn"},"artist-credit":{"name-credit":[{"artist":{"id":"43bcca8b-9edc-4997-8343-122350e790bf","name":"Fred Schneider",
"sort-name":"Schneider, Fred"}}]},"release-group":{"type":["album"]},"date":"1991-04-30","country":"us","barcode":"075992659222","asin":"075992659222",
"label-info-list":{"label-info":[{"catalog-number":"9 26592-2","label":{"name":"Reprise Records"}}]},"medium-list":{"medium":[{"format":"cd","disc-list":{"count":2},
"track-list":{"count":9}}]}}]}}

Recording

Recording searches can contain you can search:

field Description
arid artist id
artist artist name is name(s) as it appears on the recording
artistname an artist on the recording, each artist added as a seperate field
creditname name credit on the recording, each artist added as a seperate field
comment recording disambuguation comment
country recording release country
date recording release date
dur duration of track in milliseconds
format recording release format
isrc ISRC of recording
position the medium that the recording should be found on, first medium is position 1
qdur quantized duration (duration / 2000)
recording name of recording or a track associated with the recording
reid release id
release release name
rid recording id
status Release status (official, promotion, Bootleg, Pseudo-Release)
tnum track number on medium
tracks number of tracks in the medium on release
tracksrelease number of tracks on release as a whole
type Release Group type (album, single, ep, compilation, soundtrack, spokenword, interview, audiobook, live, remix, other)
tag folksonomy tag

Recording search terms with no fields search the recording field only

Example: http://www.musicbrainz.org/ws/2/recording/?query=Fred

Xml

TODO Add track pos instead of tracklist offset because a recording could match two tracks on the same release, or would it be shown within another release block?

<metadata xmlns="http://musicbrainz.org/ns/mmd-2.0#" xmlns:ext="http://musicbrainz.org/ns/ext#-2.0">
    <recording-list offset="0" count="1">
        <recording id="0b382a13-32f0-4743-9248-ba5536a6115e" ext:score="100">
            <title>King Fred</title>
            <length>160000</length>
            <artist-credit>
                <name-credit>
                    <artist id="f52f7a92-d495-4d32-89e7-8b1e5b8541c8">
                        <name>Too Much Joy</name>
                        <sort-name>Too Much Joy</sort-name>
                    </artist>
                </name-credit>
             </artist-credit>
             <release-list>
                <release id="8442e42b-c40a-4817-89a0-dbe663c94d2d">
                    <title>Green Eggs and Crack</title>
                    <release-group type="album"/>
                    <medium-list>
                        <medium>
                            <position>1</position>
                            <track-list offset="13" count="19">
                                <track>
                                    <title>King Fred</title>
                                </track>
                            </track-list>
                        </medium>
                    </medium-list>
                </release>
            </release-list>
            <puid-list>
                <puid id="1d9e8ed6-3893-4d3b-aa7d-72e79609e386"/>
            </puid-list>
        </recording>
    </recording-list>
</metadata>

If the recording belongs to a release that is a Various Artist compilation then the release will show the artist credit to allow differenitation between this and a single artist compilation.

<release id="d9127de1-ec22-4dd2-859b-c326e146fbe5">
  <title>Rock Hits</title>
  <status>Official</status>
  <artist-credit>
  <name-credit>
    <artist id="89ad4ac3-39f7-470e-963a-56509c546377">
    <name>Various Artists</name>
    </artist>
  </name-credit>
  </artist-credit>
  <release-group type="Compilation"/>
  <medium-list>
  <track-count>10</track-count>
  <medium>
  <position>1</position>
    <track-list offset="0" count="10">
      <track>
        <title>Jurk</title>
      </track>
    </track-list>
   </medium>
  </medium-list>
</release> 


Json

{"recording-list":{"offset":0,"count":1,"recording":[{"id":"0b382a13-32f0-4743-9248-ba5536a6115e","score":"100","title":"King Fred","length":160000,"artist-credit"
:{"name-credit":[{"artist":{"id":"f52f7a92-d495-4d32-89e7-8b1e5b8541c8","name":"Too Much Joy","sort-name":"Too Much Joy"}}]},"release-list":{"release"
:[{"id":"8442e42b-c40a-4817-89a0-dbe663c94d2d","title":"Green Eggs and Crack","release-group":{"type":["album"]},"medium-list":{"medium":[{"position":1,
"track-list":{"offset":13,"count":19,"track":[{"title":"King Fred"}]}}]}}]}}]}}

Label

The label index contains the following fields you can search:

field Description
alias the aliases/misspellings for this label
begin label founding date
code label code (only the figures part, i.e. without "LC")
comment label comment to differentiate similar labels
country The two letter country code of the label country
end label dissolution date
ipi ipi
label label name
sortname label sortname
type label type
tag folksonomy tag

Label search terms with no fields specified search the label, sortname and alias fields.

Example: http://www.musicbrainz.org/ws/2/label/?query=Devils

Xml

<metadata xmlns="http://musicbrainz.org/ns/mmd-2.0#" xmlns:ext="http://musicbrainz.org/ns/ext#-2.0">
    <label-list offset="0" count="1">
        <label type="original production" id="d2c296e3-10a4-4ba9-97b9-5620ff8a3ce0">
        <name>Devil's Records</name>
        <sort-name>Devil's Records</sort-name>
        <alias-list>
            <alias>Devils Records</alias>
            <alias>Devil Records</alias>
        </alias-list>
        </label>
   </label-list>
</metadata>

Json

{"label-list":{"offset":0,"count":1,"label":[{"type":"original production","id":"d2c296e3-10a4-4ba9-97b9-5620ff8a3ce0","score":"100", "name":"Devil's Records","sort-name":"Devil's Records","alias-list":{"alias":["Devils Records","Devil Records"]}}]}}}

</nowiki>

Work

The work index contains these fields you can search:

field Description
wid work id
work name of work
iswc ISWC of work
type work type
arid artist id
artist artist name, an atist in the context of a work is an artist-work relation such as composer or performer
alias the aliases/misspellings for this work
tag folksonomy tag

Work search terms with no fields specified search the work and alias fields.

Xml

<metadata xmlns="http://musicbrainz.org/ns/mmd-2.0#" xmlns:ext="http://musicbrainz.org/ns/ext#-2.0">
  <work-list offset="0" count="1">
    <work ext:score="100" id="10c1a66a-8166-32ec-a00f-540f111ce7a3">
      <title>Frozen Fred</title>
      <relation-list>
        <relation type="composer">
          <artist id="4c006444-ccbf-425e-b3e7-03a98bab5997">
            <name>Michiel Peters</name>             
            <sort-name>Peters, Michiel</sort-name>
            </artist>
        </relation>
      </relation-list>
    </work>
  </work-list>
</metadata>

Annotation

The annotation index contains the following fields you can search:

field Description
entity musicbrainz id of the entity that this annotation is about
name artist name
text the annotation itself
type the type of entity the annotation relates to (artist, release, label, track, releasegroup)

Annotation search terms with no fields specified search the text field.

Example: http://localhost:8080/ws/2/annotation/?query=mbid:bdb24cb5-404b-4f60-bba4-7b730325ae47

Xml

<metadata xmlns="http://musicbrainz.org/ns/mmd-2.0#" xmlns:ext="http://musicbrainz.org/ns/ext#-2.0">
   <annotation-list offset="0" count="1">
      <annotation type="release">
      <entity>bdb24cb5-404b-4f60-bba4-7b730325ae47</entity>
      <text>EAN: 0828768226629 - DiscID: TWj6cLku360MfFYAq_MEaT_stgc-</text>
      </annotation>
   </annotation-list>
</metadata>

Json

{"annotation-list":{"offset":0,"count":1,"annotation":[{"type":"release","entity":"bdb24cb5-404b-4f60-bba4-7b730325ae47",
"text":"EAN: 0828768226629 - DiscID: TWj6cLku360MfFYAq_MEaT_stgc-"}]}}

CdStub

The cdstub index contains these fields you can search:

field Description
artist main artist of the CD
title title of the CD
barcode barcode of the CD
comment comment
discid CD discid
tracks total tracks on the CD

CdStub index search terms with no fields search the artist and title fields only.

Example: Doo http://localhost:8080/ws/2/cdstub/?query=title:Doo Doo

Xml

<metadata xmlns="http://musicbrainz.org/ns/mmd-2.0#" xmlns:ext="http://musicbrainz.org/ns/ext#-2.0">
   <cdstub-list offset="0" count="1">
      <cdstub id="qA87dKURKperVfmckD5b_xo8BO8-">
         <title>Doo Doo First</title> 
         <artist>Doo Doo</artist>
         <barcode>837101029193</barcode>
         <comment>CD Baby id:vozzolo</comment>
         <track-list count="2"/>
      </cdstub>
   </cdstub-list>
</metadata>

Json

{"cdstub-list":{"offset":0,"count":1,"cdstub":[{"id":"qA87dKURKperVfmckD5b_xo8BO8-","title":"Doo Doo First",
"artist":"Doo Doo","barcode":"837101029193","comment":"CD Baby id:vozzolo","track-list":{"count":2}}]}}

FreeDB

The FreeDB index contains these fields you can search:

field Description
artist main artist of the this freedb release
title title of the freedb release
discid disc
category category
year year of release
tracks number of tracks on the release

FreeDB index search terms with no fields search the artist and title fields only.

Example: http://localhost:8080/ws/2/freedb/?query=artist:Ska-P

Xml

<metadata xmlns="http://musicbrainz.org/ns/mmd-2.0#" xmlns:ext="http://musicbrainz.org/ns/ext#-2.0">
   <freedb-disc-list offset="0" count="1">
      <freedb-disc id="c20c4b0d">
         <title>Lágrimas & Gozos</title>
         <artist>Ska-P</artist>
         <category>folk</category>
         <year>2008</year>
         <track-list count="13"/>
      </freedb-disc>
   </freedb-disc-list>
</metadata>

Json

{"freedb-disc-list":{"offset":0,"count":1,"freedb-disc":[{"id":"c20c4b0d","title":"Lágrimas & Gozos","artist":"Ska-P",
"category":"folk","year":"2008","track-list":{"count":13}}]}}

Tag

The Tag index contains these fields you can search:

field Description
tag tag


Example: http://localhost:8080/ws/2/tag?query=tag:rock

Xml

<metadata xmlns="http://musicbrainz.org/ns/mmd-2.0#" xmlns:ext="http://musicbrainz.org/ns/ext#-2.0">
  <tag-list offset="0" count="2">
    <tag ext:score="100"><name>rock</name></tag>
    <tag ext:score="62"><name>classic rock</name></tag>
  </tag-list></metadata>

Json

{"tag-list":{"offset":0,"count":2,"tag":[{"score":"100","name":"rock"},{"score":"62","name":"classic rock"}]}}