MusicBrainz API/Examples: Difference between revisions

From MusicBrainz Wiki
Jump to navigationJump to search
No edit summary
Line 1: Line 1:
Below you'll find examples of API requests, to get an idea of the data you'll get back and its formatting (both on XML and JSON). Some of the responses below have some fields omitted to keep the examples shorter (additional aliases, part of the release data); in the actual response the data will obviously be included.
The main web service is the [[Development/XML Web Service/Version_2|XML Web Service]]. This page is about the (beta) '''JSON''' format of that web service. For shared documentation, like the available inc= parameters, do follow the [[Development/XML Web Service/Version_2|info at the XML web service docs]]. To get a JSON response from the web service, you can either set the Accept header to "application/json" or add fmt=json to the query string (if both are set, fmt= takes precedence).

==Beta==

WARNING: This web service is available on the production server (musicbrainz.org/ws/2/) and mostly stable, but is still considered a beta, and while we do our best to avoid breaking changes, we may eventually need to make some before officially marking it as stable. If you find any issues, don't hesitate to [https://tickets.metabrainz.org/secure/Dashboard.jspa open a ticket] or contact us on IRC.


==Lookup requests==
==Lookup requests==
Below you'll find one example of a request for each entity type, to get an idea of the data you'll get back and its formatting. Some of the responses below have some fields omitted to keep the examples shorter (additional aliases, part of the release data); in the actual response the data will obviously be included.

===Area===
===Area===


Line 13: Line 7:


<div class="toccolours mw-collapsible mw-collapsed">
<div class="toccolours mw-collapsible mw-collapsed">
<div style="font-weight:bold;line-height:1.6;">Response</div>
<div style="font-weight:bold;line-height:1.6;">XML Response</div>
<pre class="mw-collapsible-content">
<metadata xmlns="http://musicbrainz.org/ns/mmd-2.0#">
<area id="45f07934-675a-46d6-a577-6f8637a411b1" type="City" type-id="6fd8f29a-3d0a-32fc-980d-ea697b69da78">
<name>P&#xE4;rnu</name>
<sort-name>P&#xE4;rnu</sort-name>
<alias-list count="2">
<alias locale="en" sort-name="P&#xE4;rnu" type="Area name" type-id="0b5b3497-d5d9-34e7-a61b-9a6c18aa7b29" primary="primary">P&#xE4;rnu</alias>
<alias locale="et" sort-name="P&#xE4;rnu" type="Area name" type-id="0b5b3497-d5d9-34e7-a61b-9a6c18aa7b29" primary="primary">P&#xE4;rnu</alias>
</alias-list>
</area>
</metadata>
</pre>
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">
<div style="font-weight:bold;line-height:1.6;">JSON Response</div>
<pre class="mw-collapsible-content">
<pre class="mw-collapsible-content">
{
{
Line 60: Line 71:


<div class="toccolours mw-collapsible mw-collapsed">
<div class="toccolours mw-collapsible mw-collapsed">
<div style="font-weight:bold;line-height:1.6;">Response</div>
<div style="font-weight:bold;line-height:1.6;">XML Response</div>
<pre class="mw-collapsible-content">
<metadata xmlns="http://musicbrainz.org/ns/mmd-2.0#">
<artist id="5b11f4ce-a62d-471e-81fc-a69a8278c7da" type="Group" type-id="e431f5f6-b5d2-343d-8b36-72607fffb74b">
<name>Nirvana</name>
<sort-name>Nirvana</sort-name>
<disambiguation>90s US grunge band</disambiguation>
<isni-list>
<isni>0000000123486830</isni>
<isni>0000000123487390</isni>
</isni-list>
<country>US</country>
<area id="489ce91b-6658-3307-9877-795b68554c98">
<name>United States</name>
<sort-name>United States</sort-name>
<iso-3166-1-code-list>
<iso-3166-1-code>US</iso-3166-1-code>
</iso-3166-1-code-list>
</area>
<begin-area id="a640b45c-c173-49b1-8030-973603e895b5">
<name>Aberdeen</name>
<sort-name>Aberdeen</sort-name>
</begin-area>
<life-span>
<begin>1988-01</begin>
<end>1994-04-05</end>
<ended>true</ended>
</life-span>
<alias-list count="2">
<alias sort-name="Nirvana US">Nirvana US</alias>
<alias locale="ja" sort-name="ニルヴァーナ" type="Artist name" type-id="894afba6-2816-3c24-8072-eadb66bd04bc" primary="primary">ニルヴァーナ</alias>
</alias-list>
</artist>
</metadata>
</pre>
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">
<div style="font-weight:bold;line-height:1.6;">JSON Response</div>
<pre class="mw-collapsible-content">
<pre class="mw-collapsible-content">
{
{
Line 92: Line 142:
},
},
isnis: ["0000000123486830", "0000000123487390"],
isnis: ["0000000123486830", "0000000123487390"],
ipis: [ ]
ipis: [ ],
aliases: [
{
end: null,
begin: null,
sort-name: "Nirvana US",
name: "Nirvana US",
type-id: null,
primary: null,
locale: null,
type: null,
ended: false
},
{
primary: true,
type-id: "894afba6-2816-3c24-8072-eadb66bd04bc",
name: "ニルヴァーナ",
sort-name: "ニルヴァーナ",
begin: null,
end: null,
ended: false,
type: "Artist name",
locale: "ja"
}
]
}
}
</pre>
</pre>

Revision as of 17:46, 10 July 2020

Below you'll find examples of API requests, to get an idea of the data you'll get back and its formatting (both on XML and JSON). Some of the responses below have some fields omitted to keep the examples shorter (additional aliases, part of the release data); in the actual response the data will obviously be included.

Lookup requests

Area

Request: https://musicbrainz.org/ws/2/area/45f07934-675a-46d6-a577-6f8637a411b1?inc=aliases&fmt=json

XML Response
<metadata xmlns="http://musicbrainz.org/ns/mmd-2.0#">
  <area id="45f07934-675a-46d6-a577-6f8637a411b1" type="City" type-id="6fd8f29a-3d0a-32fc-980d-ea697b69da78">
    <name>Pärnu</name>
    <sort-name>Pärnu</sort-name>
    <alias-list count="2">
      <alias locale="en" sort-name="Pärnu" type="Area name" type-id="0b5b3497-d5d9-34e7-a61b-9a6c18aa7b29" primary="primary">Pärnu</alias>
      <alias locale="et" sort-name="Pärnu" type="Area name" type-id="0b5b3497-d5d9-34e7-a61b-9a6c18aa7b29" primary="primary">Pärnu</alias>
    </alias-list>
  </area>
</metadata>
JSON Response
  {
    id: "45f07934-675a-46d6-a577-6f8637a411b1",
    name: "Pärnu",
    type-id: "6fd8f29a-3d0a-32fc-980d-ea697b69da78",
    type: "City",
    disambiguation: "",
    life-span: {
      begin: null,
      end: null,
      ended: false
    },
    aliases: [
      {
        name: "Pärnu",
        sort-name: "Pärnu",
        type-id: "0b5b3497-d5d9-34e7-a61b-9a6c18aa7b29",
        type: "Area name",
        locale: "en",
        primary: true,
        begin: null,
        end: null,
        ended: false
      },
      {
        name: "Pärnu",
        sort-name: "Pärnu",
        type-id: "0b5b3497-d5d9-34e7-a61b-9a6c18aa7b29",
        type: "Area name",
        locale: "et",
        primary: true,
        begin: null,
        end: null,
        ended: false
      }
    ]
  }

Artist

Request: http://musicbrainz.org/ws/2/artist/5b11f4ce-a62d-471e-81fc-a69a8278c7da?inc=aliases&fmt=json

XML Response
<metadata xmlns="http://musicbrainz.org/ns/mmd-2.0#">
  <artist id="5b11f4ce-a62d-471e-81fc-a69a8278c7da" type="Group" type-id="e431f5f6-b5d2-343d-8b36-72607fffb74b">
    <name>Nirvana</name>
    <sort-name>Nirvana</sort-name>
    <disambiguation>90s US grunge band</disambiguation>
    <isni-list>
      <isni>0000000123486830</isni>
      <isni>0000000123487390</isni>
    </isni-list>
    <country>US</country>
    <area id="489ce91b-6658-3307-9877-795b68554c98">
      <name>United States</name>
      <sort-name>United States</sort-name>
      <iso-3166-1-code-list>
        <iso-3166-1-code>US</iso-3166-1-code>
      </iso-3166-1-code-list>
    </area>
    <begin-area id="a640b45c-c173-49b1-8030-973603e895b5">
      <name>Aberdeen</name>
      <sort-name>Aberdeen</sort-name>
    </begin-area>
    <life-span>
      <begin>1988-01</begin>
      <end>1994-04-05</end>
      <ended>true</ended>
    </life-span>
    <alias-list count="2">
      <alias sort-name="Nirvana US">Nirvana US</alias>
      <alias locale="ja" sort-name="ニルヴァーナ" type="Artist name" type-id="894afba6-2816-3c24-8072-eadb66bd04bc" primary="primary">ニルヴァーナ</alias>
    </alias-list>
  </artist>
</metadata>
JSON Response
  {
    id: "5b11f4ce-a62d-471e-81fc-a69a8278c7da",
    name: "Nirvana",
    sort-name: "Nirvana",
    type-id: "e431f5f6-b5d2-343d-8b36-72607fffb74b",
    type: "Group",
    disambiguation: "90s US grunge band",
    gender: null,
    gender-id: null,
    country: "US",
    area: {
      disambiguation: "",
      id: "489ce91b-6658-3307-9877-795b68554c98",
      sort-name: "United States",
      name: "United States",
      iso-3166-1-codes: ["US"]
    },
    begin-area: {
      id: "a640b45c-c173-49b1-8030-973603e895b5",
      disambiguation: "",
      name: "Aberdeen",
      sort-name: "Aberdeen"
    },
    end-area: null,
    life-span: {
      ended: true,
      begin: "1988-01",
      end: "1994-04-05"
    },
    isnis: ["0000000123486830", "0000000123487390"],
    ipis: [ ],
    aliases: [
      {
        end: null,
        begin: null,
        sort-name: "Nirvana US",
        name: "Nirvana US",
        type-id: null,
        primary: null,
        locale: null,
        type: null,
        ended: false
      },
      {
        primary: true,
        type-id: "894afba6-2816-3c24-8072-eadb66bd04bc",
        name: "ニルヴァーナ",
        sort-name: "ニルヴァーナ",
        begin: null,
        end: null,
        ended: false,
        type: "Artist name",
        locale: "ja"
      }
    ]
  }

Event

For events, you'll generally want to include at least artist-rels (for performers) and place-rels (for location), as in the example below.

Request: https://musicbrainz.org/ws/2/event/fe39727a-3d21-4066-9345-3970cbd6cca4?inc=aliases+artist-rels+place-rels&fmt=json

Response
  {
    id: "fe39727a-3d21-4066-9345-3970cbd6cca4",
    name: "Nine Inch Nails at Arena Riga",
    disambiguation: "",
    type-id: "ef55e8d7-3d00-394a-8012-f5506a29ff0b",
    type: "Concert",
    life-span: {
      end: "2014-05-06",
      ended: true,
      begin: "2014-05-06"
    },
    time: "19: 00",
    cancelled: false,
    setlist: "* Copy of A * 1,000,000 * Terrible Lie * March of the Pigs * Piggy * The Frail * The Wretched * The Becoming * Gave Up * Closer * Find My Way * Me, I'm Not * Came Back Haunted * The Great Destroyer * Eraser * Wish * Burn * The Hand That Feeds * Head Like a Hole # Encore * Hurt",
    relations: [
      {
        type-id: "936c7c95-3156-3889-a062-8a0cd57f8946",
        type: "main performer",
        direction: "backward",
        target-type: "artist",
        artist: {
          id: "b7ffd2af-418f-4be2-bdd1-22f8b48613da",
          name: "Nine Inch Nails",
          sort-name: "Nine Inch Nails",
          disambiguation: ""
        },
        begin: null,
        end: null,
        ended: false,
        target-credit: "",
        source-credit: "",
        attributes: [ ],
        attribute-ids: { },
        attribute-values: { }
      },
      {
        type-id: "492a850e-97eb-306a-a85e-4b6d98527796",
        type: "support act",
        direction: "backward",
        target-type: "artist",
        artist: {
          id: "f7f32d93-0801-45cb-9f5a-e68f640649f4",
          name: "Cold Cave",
          sort-name: "Cold Cave",
          disambiguation: ""
        },
        begin: null,
        end: null,
        ended: false,
        target-credit: "",
        source-credit: "",
        attributes: [ ],
        attribute-ids: { },
        attribute-values: { }
      },
      {
        type-id: "e2c6f697-07dc-38b1-be0b-83d740165532",
        type: "held at",
        direction: "forward",
        target-type: "place",
        place: {
          id: "478558f9-a951-4067-ad91-e83f6ba63e74",
          name: "Arēna Rīga",
          address: "Skanstes iela 21, Rīga, Latvia",
          coordinates: {
            longitude: 24.121403,
            latitude: 56.967989
          },
          disambiguation: "",
          type-id: "a77c11f6-82fa-3cc0-9041-ac60e5f6e024",
          type: "Indoor arena",
          area: {
            id: "9c612199-d66f-4109-aedc-67ab26e0a43b",
            name: "Rīga",
            sort-name: "Rīga",
            disambiguation: "",
            iso-3166-2-codes: ["LV-RIX"]
          }
        },
        begin: null,
        end: null,
        ended: false,
        target-credit: "",
        source-credit: "",
        attributes: [ ],
        attribute-ids: { },
        attribute-values: { }
      }
    ],
    aliases: [ ]
  }

Genre

Request: http://musicbrainz.org/ws/2/genre/f66d7266-eb3d-4ef3-b4d8-b7cd992f918b?fmt=json

Response
  {
     id: "f66d7266-eb3d-4ef3-b4d8-b7cd992f918b"
     name: "crust punk",
     disambiguation: "",
  }

Instrument

Request: https://musicbrainz.org/ws/2/instrument/dd430e7f-36ba-49a5-825b-80a525e69190?inc=aliases&fmt=json

Response
  {
    id: "dd430e7f-36ba-49a5-825b-80a525e69190",
    name: "kemanak",
    disambiguation: "Banana shaped bronze slit-drum used in javanese gamelan",
    description: "Bent into a ladle or banana like shape, it is a pair of bronze slit-drums hit with tabuh beaters.",
    type-id: "68fa2525-4c23-3386-bb81-e84994342e9a",
    type: "Percussion instrument",
    aliases: [
      {
        name: "gumanak",
        sort-name: "gumanak",
        type-id: "2322fc94-fbf3-3c09-b23c-aa5ec8d14fcd",
        type: "Instrument name",
        locale: null,
        primary: null,
        begin: null,
        end: null,
        ended: false
      },
      {
        name: "kenawak",
        sort-name: "kenawak",
        type-id: "2322fc94-fbf3-3c09-b23c-aa5ec8d14fcd",
        type: "Instrument name",
        locale: null,
        primary: null,
        begin: null,
        end: null,
        ended: false
      }
    ]
  }

Label

Request: http://musicbrainz.org/ws/2/label/46f0f4cd-8aab-4b33-b698-f459faf64190?inc=aliases&fmt=json

Response
  {
    id: "46f0f4cd-8aab-4b33-b698-f459faf64190",
    name: "Warp",
    disambiguation: "UK independent label",
    type-id: "7aaa37fe-2def-3476-b359-80245850062d",
    type: "Original Production",
    label-code: 2070,
    life-span: {
      begin: "1989",
      end: null,
      ended: false
    },
    aliases: [
      {
        name: "Warp Records",
        sort-name: "Warp Records",
        type-id: "3a1a0c48-d885-3b89-87b2-9e8a483c5675",
        type: "Label name",
        locale: "en_GB",
        primary: false,
        begin: null,
        end: null,
        ended: false
      }
    ],
    country: "GB",
    area: {
      id: "8a754a16-0027-3a29-b6d7-2b40ea0481ed",
      name: "United Kingdom",
      sort-name: "United Kingdom",
      disambiguation: ""
      iso-3166-1-codes: ["GB"],
    },
    ipis: [ ],
    isnis: ["0000000107280584"]
  }

Place

Request: https://musicbrainz.org/ws/2/place/478558f9-a951-4067-ad91-e83f6ba63e74?inc=aliases&fmt=json

Response
  {
    id: "478558f9-a951-4067-ad91-e83f6ba63e74",
    name: "Arēna Rīga",
    disambiguation: "",
    type-id: "a77c11f6-82fa-3cc0-9041-ac60e5f6e024",
    type: "Indoor arena",
    address: "Skanstes iela 21, Rīga, Latvia",
    life-span: {
      begin: "2006-02-15",
      end: null,
      ended: false
    },
    coordinates: {
      longitude: 24.121403,
      latitude: 56.967989
    },
    aliases: [
      {
        name: "Arena Riga",
        sort-name: "Arena Riga",
        type-id: "fb68f9a2-622c-319b-83b0-bbff4127cdc5",
        type: "Place name",
        locale: "en",
        primary: true,
        begin: null,
        end: null,
        ended: false
      }
    ],
    area: {
      id: "9c612199-d66f-4109-aedc-67ab26e0a43b",
      name: "Rīga",
      sort-name: "Rīga",
      disambiguation: "",
      iso-3166-2-codes: ["LV-RIX"]
    },
  }

Recording

Request: https://musicbrainz.org/ws/2/recording/b9ad642e-b012-41c7-b72a-42cf4911f9ff?inc=artist-credits+isrcs+releases&fmt=json

Response
  {
    id: "b9ad642e-b012-41c7-b72a-42cf4911f9ff",
    title: "LAST ANGEL",
    artist-credit: [
      {
        name: "倖田來未",
        joinphrase: " feat. ",
        artist: {
          id: "455641ea-fff4-49f6-8fb4-49f961d8f1ac",
          name: "倖田來未",
          disambiguation: "",
          sort-name: "Koda, Kumi"
        }
      },
      {
        name: "東方神起",
        joinphrase: "",
        artist: {
          id: "05cbaf37-6dc2-4f71-a0ce-d633447d90c3",
          name: "東方神起",
          disambiguation: "",
          sort-name: "Tohoshinki"
        }
      }
    ],
    disambiguation: "",
    length: 230000,
    video: false,
    isrcs: ["JPB600760301"],
    releases: [
      {
        id: "c33dee6a-e053-4272-84ad-dfeef3f48c8a",
        title: "LAST ANGEL",
        /* some properties omitted to keep this example shorter, see the release results for the full format */
      },
      {
        id: "601a4558-e416-410b-a64c-857fc133b75c",
        title: "Kingdom",
        /* some properties omitted to keep this example shorter, see the release results for the full format */
      }
    ]
  }

Release

Request: http://musicbrainz.org/ws/2/release/59211ea4-ffd2-4ad9-9a4e-941d3148024a?inc=artist-credits+labels+discids+recordings&fmt=json

Response
  {
    id: "59211ea4-ffd2-4ad9-9a4e-941d3148024a",
    title: "æ³o & h³æ",
    disambiguation: "",
    artist-credit: [
      {
        name: "Autechre",
        joinphrase: " & ",
        artist: {
          id: "410c9baf-5469-44f6-9852-826524b80c61",
          name: "Autechre",
          sort-name: "Autechre",
          disambiguation: "English electronic music duo Rob Brown & Sean Booth"
        }
      },
      {
        name: "The Hafler Trio",
        joinphrase: "",
        artist: {
          id: "146c01d0-d3a2-44c3-acb5-9208bce75e14",
          name: "The Hafler Trio",
          sort-name: "Hafler Trio, The",
          disambiguation: ""
        }
      }
    ],
    date: "2003-12-04",
    country: "GB",
    release-events: [
      {
        date: "2003-12-04",
        area: {
          id: "8a754a16-0027-3a29-b6d7-2b40ea0481ed",
          name: "United Kingdom",
          sort-name: "United Kingdom",
          iso-3166-1-codes: ["GB"],
          disambiguation: ""
        }
      }
    ],
    label-info: [
      {
        catalog-number: "pgram002",
        label: {
          id: "a0759efa-f583-49ea-9a8d-d5bbce55541c",
          name: "Phonometrography",
          disambiguation: "",
          label-code: null
        }
      }
    ],
    barcode: null,
    packaging-id: null,
    packaging: null,
    status-id: "4e304316-386d-3409-af2e-78857eec5cfe",
    status: "Official",
    quality: "normal",
    text-representation: {
      language: "eng",
      script: "Latn"
    },
    asin: null,
    media: [
      {
        discs: [
          {
            id: "nN2g3a0ZSjovyIgK3bJl6_.j8C4-",
            sectors: 73241,
            offsets: [150],
            offset-count: 1
          }
        ],
        position: 1,
        title: "æ³o",
        format-id: "9712d52a-4509-3d4b-a1a2-67c88c643e31",
        format: "CD",
        track-count: 1,
        track-offset: 0,
        tracks: [
          {
            id: "61af3e5a-14e0-350d-9826-a884c6e586b1",
            title: "æ³o",
            length: 974546,
            number: "1",
            position: 1,
            artist-credit: [
              {
                name: "Autechre",
                joinphrase: " & ",
                artist: {
                  id: "410c9baf-5469-44f6-9852-826524b80c61",
                  name: "Autechre",
                  sort-name: "Autechre",
                  disambiguation: "English electronic music duo Rob Brown & Sean Booth"
                }
              },
              {
                name: "The Hafler Trio",
                joinphrase: "",
                artist: {
                  id: "146c01d0-d3a2-44c3-acb5-9208bce75e14",
                  name: "The Hafler Trio",
                  sort-name: "Hafler Trio, The",
                  disambiguation: ""
                }
              }
            ],
            recording: {
              id: "af87f070-238b-46c1-aa3e-f831ab91fa20",
              title: "æ³o",
              disambiguation: "",
              length: 974546,
              video: false,
              artist-credit: [
                {
                  name: "Autechre",
                  joinphrase: " & ",
                  artist: {
                    id: "410c9baf-5469-44f6-9852-826524b80c61",
                    name: "Autechre",
                    sort-name: "Autechre",
                    disambiguation: "English electronic music duo Rob Brown & Sean Booth"
                  }
                },
                {
                  name: "The Hafler Trio",
                  joinphrase: "",
                  artist: {
                    id: "146c01d0-d3a2-44c3-acb5-9208bce75e14",
                    name: "The Hafler Trio",
                    sort-name: "Hafler Trio, The",
                    disambiguation: ""
                  }
                }
              ]
            }
          }
        ]
      },
      {
        position: 2,
        title: "h³æ",
        format-id: "9712d52a-4509-3d4b-a1a2-67c88c643e31",
        format: "CD",
        track-count: 1,
        track-offset: 0,
        discs: [
          {
            id: "aSHvkMnq2jZVFEK.DmSPbvN_f54-",
            sectors: 69341,
            offsets: [150],
            offset-count: 1
          }
        ],
        tracks: [
          {
            id: "5f2031a2-c67d-3bec-8ae5-8d22847ab0a5",
            title: "h³æ",
            length: 922546,
            number: "1",
            position: 1,
            artist-credit: [
              {
                name: "Autechre",
                joinphrase: " & ",
                artist: {
                  id: "410c9baf-5469-44f6-9852-826524b80c61",
                  name: "Autechre",
                  sort-name: "Autechre",
                  disambiguation: "English electronic music duo Rob Brown & Sean Booth"
                }
              },
              {
                name: "The Hafler Trio",
                joinphrase: "",
                artist: {
                  id: "146c01d0-d3a2-44c3-acb5-9208bce75e14",
                  name: "The Hafler Trio",
                  sort-name: "Hafler Trio, The",
                  disambiguation: ""
                }
              }
            ],
            recording: {
              id: "5aff6309-2e02-4a47-9233-32d7dcc9a960",
              title: "h³æ",
              disambiguation: "",
              length: 922546,
              video: false,
              artist-credit: [
                {
                  name: "Autechre",
                  joinphrase: " & ",
                  artist: {
                    id: "410c9baf-5469-44f6-9852-826524b80c61",
                    name: "Autechre",
                    sort-name: "Autechre",
                    disambiguation: "English electronic music duo Rob Brown & Sean Booth"
                  }
                },
                {
                  name: "The Hafler Trio",
                  joinphrase: "",
                  artist: {
                    id: "146c01d0-d3a2-44c3-acb5-9208bce75e14",
                    name: "The Hafler Trio",
                    sort-name: "Hafler Trio, The",
                    disambiguation: ""
                  }
                }
              ]
            }
          }
        ]
      }
    ],
    cover-art-archive: {
      count: 1,
      artwork: true,
      front: true,
      back: false,
      darkened: false
    }
  }

Release Group

Request: http://musicbrainz.org/ws/2/release-group/c9fdb94c-4975-4ed6-a96f-ef6d80bb7738?inc=artist-credits+releases&fmt=json

Response
 {
     id: "c9fdb94c-4975-4ed6-a96f-ef6d80bb7738",
     title: "The Lost Tape",
     first-release-date: "2012-05-22",
     artist-credit: [
         "name": "50 Cent",
         "joinphrase": "",
         "artist": {
             "id": "8e68819d-71be-4e7d-b41d-f1df81b01d3f",
             "name": "50 Cent",
             "sort-name": "50 Cent",
             "disambiguation": ""
         }
     ],
     disambiguation: null,
     primary-type-id: "f529b476-6e62-324f-b0aa-1f3e33d313fc",
     primary-type: "Album",
     secondary-type-ids: ["15c1b1f5-d893-3375-a1db-e180c5ae15ed"]
     secondary-types: [ "Mixtape/Street" ],
     releases: [
         {
             "id": "2ec84eb6-ab92-4ac3-9720-32ad84c34f11",
             "title": "The Lost Tape",
             /* some properties omitted to keep this example shorter, see the release results for the full format */
         }
     ]
  }

URL

Request: https://musicbrainz.org/ws/2/url/46d8f693-52e4-4d03-936f-7ca8459019a7?fmt=json

Response
  {
    id: "46d8f693-52e4-4d03-936f-7ca8459019a7",
    resource: "https://www.arvopart.ee/"
  }

Work

For works, you'll generally want to include at least artist-rels (for writers), as in the example below.

Request: http://musicbrainz.org/ws/2/work/b1df2cf3-69a9-3bc0-be44-f71e79b27a22?inc=artist-rels&fmt=json

Response
  {
    id: "b1df2cf3-69a9-3bc0-be44-f71e79b27a22",
    title: "HELLO! また会おうね",
    type-id: "f061270a-2fd6-32f1-a641-f0f8676d14e6"
    type: "Song",
    disambiguation: "",
    iswcs: ["T-101.690.320-9"],
    languages: ["jpn"],
    attributes: [
      {
        type-id: "31048fcc-3dbb-3979-8f85-805afb933e0c",
        type: "JASRAC ID",
        value: "089-5005-9"
      }
    ],
    relations: [
      {
        type-id: "d59d99ea-23d4-4a80-b066-edca32ee158f",
        type: "composer",
        direction: "backward",
        target-type: "artist",
        artist: {
          id: "d997d399-355e-4c49-9c7b-75a93d76bc0e",
          name: "つんく♂",
          sort-name: "Tsunku",
          disambiguation: ""
        },
        source-credit: "",
        target-credit: "",
        attributes: [ ],
        attribute-ids: { },
        attribute-values: { },
        begin: null,
        end: null,
        ended: false
      },
        type-id: "3e48faba-ec01-47fd-8e89-30e81161661c",
        type: "lyricist",
        direction: "backward",
        target-type: "artist",
        artist: {
          id: "d997d399-355e-4c49-9c7b-75a93d76bc0e",
          name: "つんく♂",
          sort-name: "Tsunku",
          disambiguation: ""
        },
        source-credit: "",
        target-credit: "",
        attributes: [ ],
        attribute-ids: { },
        attribute-values: { },
        begin: null,
        end: null,
        ended: false
      }
    ]
  }

Browse Requests

Browse requests are a direct lookup of all the entities directly linked to another entity. You can see more info about what types you can browse each entity type by if you check the documentation for XML browse requests (most of the documentation applies as-is to the JSON version of the web service).

Browse requests return a top-level object with offset and count properties to help with paging, and a property for the requested entity. Unless you set a limit (see example below) you will get 25 results per page.

The key for the entity property will be the English plural of the entity name, so: areas, artists, events, instruments, labels, places, recordings, releases, release-groups, series or works.

Browse requests are not currently available for genres.

Request: http://musicbrainz.org/ws/2/release?label=47e718e1-7ee4-460c-b1cc-1192a841c6e5&offset=12&limit=2&fmt=json

Response
  {
    releases: [
      {
        id: "0b405ea7-8785-402f-bcf7-d55f5000dc3e",
        title: "Wintertunes"
        /* some properties omitted to keep this example shorter, see the release results for the full format */
      },
      {
        id: "7eb37a3a-646d-4501-a373-e9071186b88d",
        title: "Adventure Magic Supreme Journey Music"
        /* some properties omitted to keep this example shorter, see the release results for the full format */
      }
    ],
    release-offset: 12,
    release-count: 106
  }

Relationships

You can request relationships with the appropriate includes:

  • 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

These will load relationships between the requested entity and the specific entity type. For example, if you request "work-rels" when looking up an artist, you'll get all the relationships between this artist and any works, and if you request "artist-rels" you'll get the relationships between this artist and any other artists. As such, keep in mind requesting "artist-rels" for an artist, "release-rels" for a release, etc. will not load all the relationships for the entity, just the ones to other entities of the same type.

You can find examples of relationship requests above, under Event and Work.

in a release request, you might also be interested on relationships for the recordings linked to the release, or even for the works linked to those recordings (for example, to find out who played guitar on a specific track or who wrote the lyrics for the song being performed). Similarly, for a recording request, you might want to get the relationships for any linked works. There are two additional includes for this:

  • recording-level-rels
  • work-level-rels

Keep in mind these just act as switches. If you request work-level-rels for a recording, you will still need to request work-rels (to get the relationship from the recording to the work in the first place) and any other relationship types you want to see (for example, artist-rels if you want to see work-artist relationships). See the example below for a one-track classical release with both performers (recording level relationships) and composer (work level relationship).

Request: https://musicbrainz.org/ws/2/release/987f3e2d-22a6-4a4f-b840-c80c26b8b91a?inc=artist-credits+labels+recordings+recording-level-rels+work-rels+work-level-rels+artist-rels&fmt=json

Response
  {
    id: "987f3e2d-22a6-4a4f-b840-c80c26b8b91a",
    title: "Become Desert",
    disambiguation: "",
    artist-credit: [
      {
        name: "John Luther Adams",
        joinphrase: "; ",
        artist: {
          id: "96681463-98e2-4032-9728-5fbb7b002427",
          name: "John Luther Adams",
          sort-name: "Adams, John Luther",
          disambiguation: ""
        }
      },
      {
        name: "Seattle Symphony",
        joinphrase: ", ",
        artist: {
          id: "0b51c328-1f2b-464c-9e2c-0c2a8cce20ae",
          name: "Seattle Symphony",
          sort-name: "Seattle Symphony",
          disambiguation: ""
        }
      },
      {
        name: "Ludovic Morlot",
        joinphrase: "",
        artist: {
          id: "eace8da8-8535-47c4-82da-902c792ec9f4",
          name: "Ludovic Morlot",
          sort-name: "Morlot, Ludovic",
          disambiguation: ""
        }
      }
    ],
    text-representation: {
      language: "eng",
      script: "Latn"
    },
    date: "2019-06-14",
    country: "XW",
    release-events: [
      {
        date: "2019-06-14",
        area: {
          id: "525d4e18-3d00-31b9-a58b-a146a916de8f",
          name: "[Worldwide]",
          sort-name: "[Worldwide]",
          disambiguation: "",
          iso-3166-1-codes: ["XW"]
        }
      }
    ],
    label-info: [
      {
        label: {
          id: "3044afdb-c895-4f60-8e69-5796b3887c21",
          sort-name: "Cantaloupe Music",
          name: "Cantaloupe Music",
          label-code: null,
          disambiguation: ""
        },
        catalog-number: null
      }
    ],
    barcode: null,
    status-id: "4e304316-386d-3409-af2e-78857eec5cfe",
    status: "Official",
    packaging-id: "119eba76-b343-3e02-a292-f0f00644bb9b",
    packaging: "None",
    quality: "normal",
    relations: [ ],
    asin: null,
    media: [
      {
        position: 1,
        format-id: "907a28d9-b3b2-3ef6-89a8-7b18d91d4794",
        format: "Digital Media",
        title: "",
        track-count: 1,
        track-offset: 0,
        tracks: [
          {
            id: "33781879-1dae-422c-a634-b26f89705e48",
            title: "Become Desert",
            length: 2422450,
            number: "1",
            position: 1,
            artist-credit: [
              {
                name: "John Luther Adams",
                joinphrase: "",
                artist: {
                  id: "96681463-98e2-4032-9728-5fbb7b002427",
                  name: "John Luther Adams",
                  sort-name: "Adams, John Luther",
                  disambiguation: ""
                }
              }
            ],
            recording: {
              id: "d90bc0ff-c7d9-4c09-a12b-d46f46f7281d",
              title: "Become Desert",
              disambiguation: "",
              length: 2422450,
              video: false,
              artist-credit: [
                {
                  name: "Seattle Symphony",
                  joinphrase: ", ",
                  artist: {
                    id: "0b51c328-1f2b-464c-9e2c-0c2a8cce20ae",
                    name: "Seattle Symphony",
                    sort-name: "Seattle Symphony",
                    disambiguation: ""
                  }
                },
                {
                  name: "Ludovic Morlot",
                  joinphrase: "",
                  artist: {
                    id: "eace8da8-8535-47c4-82da-902c792ec9f4",
                    sort-name: "Morlot, Ludovic",
                    disambiguation: "",
                    name: "Ludovic Morlot"
                  }
                }
              ],
              relations: [
                {
                  type-id: "234670ce-5f22-4fd0-921b-ef1662695c5d",
                  type: "conductor",
                  direction: "backward",
                  target-type: "artist",
                  artist: {
                    id: "eace8da8-8535-47c4-82da-902c792ec9f4",
                    name: "Ludovic Morlot",
                    sort-name: "Morlot, Ludovic",
                    disambiguation: ""
                  },
                  begin: "2018-09-25",
                  end: "2018-09-26",
                  ended: true,
                  target-credit: "",
                  source-credit: "",
                  attributes: [ ],
                  attribute-values: { },
                  attribute-ids: { }
                },
                {
                  type-id: "3b6616c5-88ba-4341-b4ee-81ce1e6d7ebb",
                  type: "performing orchestra",
                  direction: "backward",
                  target-type: "artist",
                  artist: {
                    id: "0b51c328-1f2b-464c-9e2c-0c2a8cce20ae",
                    name: "Seattle Symphony",
                    sort-name: "Seattle Symphony",
                    disambiguation: ""
                  },
                  begin: "2018-09-25",
                  end: "2018-09-26",
                  ended: true,
                  target-credit: "",
                  source-credit: "",
                  attributes: [ ],
                  attribute-values: { },
                  attribute-ids: { }
                },
                {
                  type-id: "a01ee869-80a8-45ef-9447-c59e91aa7926",
                  type: "recording",
                  direction: "backward",
                  target-type: "artist",
                  artist: {
                    id: "e2a6142d-83f5-4626-a48a-1211588d06db",
                    name: "Alexander Lipay",
                    sort-name: "Lipay, Alexander",
                    disambiguation: ""
                  },
                  begin: null,
                  end: null,
                  ended: false,
                  target-credit: "",
                  source-credit: "",
                  attributes: [ ],
                  attribute-values: { },
                  attribute-ids: { }
                },
                {
                  type-id: "a3005666-a872-32c3-ad06-98af558e99b0",
                  type: "performance",
                  direction: "forward",
                  target-type: "work",
                  work: {
                    id: "b6cb19ec-08d3-4563-9e82-9562e5cab030",
                    title: "Become Desert",
                    disambiguation: "",
                    type-id: null,
                    type: null,
                    languages: ["zxx"],
                    iswcs: [ ],
                    attributes: [ ],
                    relations: [
                      {
                        type-id: "d59d99ea-23d4-4a80-b066-edca32ee158f",
                        type: "composer",
                        direction: "backward",
                        target-type: "artist",
                        artist: {
                          id: "96681463-98e2-4032-9728-5fbb7b002427",
                          name: "John Luther Adams",
                          sort-name: "Adams, John Luther",
                          disambiguation: ""
                        },
                        begin: null,
                        end: null,
                        ended: false,
                        source-credit: "",
                        target-credit: "",
                        attributes: [ ],
                        attribute-ids: { },
                        attribute-values: { }
                      },
                      {
                        type-id: "95f0213a-dbe0-4d36-8036-9782e425e98a",
                        type: "commissioned",
                        direction: "backward",
                        target-type: "artist",
                        artist: {
                          id: "7cdb68bc-c4f1-4a92-9bd2-739641c5eff0",
                          name: "New York Philharmonic",
                          sort-name: "New York Philharmonic",
                          disambiguation: ""
                        },
                        begin: null,
                        end: null,
                        ended: false,
                        source-credit: "",
                        target-credit: "",
                        attributes: [ ],
                        attribute-ids: { },
                        attribute-values: { }
                      }
                    ]
                  },
                  begin: "2018-09-25",
                  end: "2018-09-26",
                  ended: true,
                  target-credit: "",
                  source-credit: "",
                  attributes: [ ],
                  attribute-ids: { },
                  attribute-values: { }
                }
              ]
            }
          }
        ]
      }
    ],
    cover-art-archive: {
      artwork: true,
      count: 1,
      front: true,
      back: false,
      darkened: false
    }
  }

Genres, Tags and Ratings

You can include genres, tags and ratings to get this secondary data. Below is an example of a request including all of the three.

Request: http://musicbrainz.org/ws/2/artist/db92a151-1ac2-438b-bc43-b82e149ddd50?inc=aliases+genres+tags+ratings&fmt=json

Response
  {
    id: "db92a151-1ac2-438b-bc43-b82e149ddd50",
    name: "Rick Astley",
    sort-name: "Astley, Rick",
    disambiguation: "English singer, songwriter and radio personality",
    type-id: "b6e035f4-3ce9-331c-97df-83397230b0df",
    type: "Person",
    gender-id: "36d3d30a-839d-3eda-8cb3-29be4384e4a9",
    gender: "Male",
    life-span: {
      end: null,
      ended: false,
      begin: "1966-02-06"
    },
    country: "GB"
    area: {
      id: "8a754a16-0027-3a29-b6d7-2b40ea0481ed",
      name: "United Kingdom",
      sort-name: "United Kingdom",
      disambiguation: "",
      iso-3166-1-codes: ["GB"]
    },
    begin-area: {
      id: "71baf484-64ec-4482-9ad2-225aa3b9a337"
      name: "Newton-le-Willows",
      sort-name: "Newton-le-Willows",
      disambiguation: "",
    },
    end-area: null,
    ipis: ["00159849414"],
    isnis: ["0000000120203276"],
    aliases: [
      {
        name: "Richard Paul Astley",
        sort-name: "Astley, Richard Paul",
        type-id: "d4dcd0c0-b341-3612-a332-c0ce797b25cf",
        type: "Legal name",
        locale: null,
        primary: null,
        begin: null,
        end: null
        ended: false,
      }
    ],
    genres: [
      {name: "blue-eyed soul", count: 2}
    ],
    tags: [
      {name: "blue-eyed soul", count: 2},
      {name: "british", count: 1}
    ],
    rating: {
      value: 4.5,
      votes-count: 2
    }
  }