Difference between revisions of "MusicBrainz API/Examples"

From MusicBrainz Wiki
m (Lookup requests)
(Area)
Line 9: Line 9:
  
 
===Area===
 
===Area===
 +
 +
Request: https://musicbrainz.org/ws/2/area/45f07934-675a-46d6-a577-6f8637a411b1?inc=aliases&fmt=json
 +
 +
<div class="toccolours mw-collapsible mw-collapsed">
 +
<div style="font-weight:bold;line-height:1.6;">Response</div>
 +
<pre class="mw-collapsible-content">
 +
  {
 +
    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
 +
      }
 +
    ]
 +
  }
 +
</pre>
 +
</div>
 +
</div>
  
 
===Artist===
 
===Artist===

Revision as of 10:34, 6 March 2020

The main web service is the 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 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 open a ticket or contact us on IRC.

Lookup requests

Some of the responses below have some fields omitted to keep the examples shorter, in the actual response the data will obviously be included.

Area

Request: https://musicbrainz.org/ws/2/area/45f07934-675a-46d6-a577-6f8637a411b1?inc=aliases&fmt=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

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: [ ]
  }

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

Event

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

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

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 */
         }
     ]
  }

Work

Request: http://musicbrainz.org/ws/2/work/b1df2cf3-69a9-3bc0-be44-f71e79b27a22?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"
      }
    ],
  }

Browse Requests

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

Request: http://musicbrainz.org/ws/2/release/275b01eb-8551-47ff-bd6b-2d142b4bf422?inc=url-rels&fmt=json

Response:

 {
     "id": "275b01eb-8551-47ff-bd6b-2d142b4bf422",
     "title": "Kraftwerk Kover Kollection, Volume 1",
     "quality": "normal",
     "text-representation": { "language": "eng", "script": "Latn" },
     "date": "2012",
     "relations": [
         {
             "direction": "backward",
             "type": "download for free",
             "url": "http://soundcloud.com/strictly/kraftwerk-kover-kollection-vol"
         }
     ],
     "country": null,
     "status": null,
     "barcode": null,
     "disambiguation": null,
     "packaging": null,
     "asin": null
 }

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

Response:

 {
   "id": "b1df2cf3-69a9-3bc0-be44-f71e79b27a22",
   "title": "HELLO! また会おうね",
   "language": "jpn",
   "iswcs": [ "T-101.690.320-9" ],
   "relations": [
         {
             "direction": "backward",
             "type": "composer",
             "artist": {
                 "id": "d997d399-355e-4c49-9c7b-75a93d76bc0e",
                 "name": "つんく♂",
                 "sort-name": "Tsunku",
                 "disambiguation": null
             }
         },
         {
             "direction": "backward",
             "type": "lyricist",
             "artist": {
                 "id": "d997d399-355e-4c49-9c7b-75a93d76bc0e",
                 "name": "つんく♂",
                 "sort-name": "Tsunku",
                 "disambiguation": null
             }
         },
         {
             "direction": "backward",
             "type": "performance",
             "recording": {
                 "id": "487cac92-eed5-4efa-8563-c9a818079b9a",
                 "title": "HELLO! また会おうね (7人祭 version)",
                 "length": 283600,
                 "disambiguation": null
             }
         },
         {
             "type": "performance",
             "direction": "backward",
             "recording": {
                 "id": "fd3061c1-cb9a-4698-bc5f-f6e0e6a36272",
                 "title": "HELLO! また会おうね (20人祭 version)",
                 "length": 283600,
                 "disambiguation": "PV"
             }
         }
     ]
 }