MusicBrainz API/Examples

From MusicBrainz Wiki
Jump to navigationJump to search

This document describes the proposed JSON output, using example queries and the responses I am proposing. Getting a JSON response will require setting the Accept header to "application/json".

Some notable differences compared to the JSON response currently used internally by the search server:

  1. all "-list" elements are replaced with javascript arrays, using an english plural as the key. So { "tag-list": { "tag": [ ... ] } } becomes { "tags": [ ... ] }.
  2. the "name-credit" key inside an "artist-credit" is removed.

A notable change from the XML response is to completely drop the "target-type" attribute on relations (you can easily get only e.g. url relationships by ignoring all relationship objects which don't have a "url" property, so it seemed simpler to just have a single list of relations).

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

Lookup requests

Artist

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

{
    "id": "5b11f4ce-a62d-471e-81fc-a69a8278c7da"
    "name": "Nirvana",
    "sort-name": "Nirvana"
    "type": "Group",
    "country": "US",
    "disambiguation": "90s US grunge band",
    "life-span": {
        "ended": true,
        "begin": "1988-02",
        "end": "1994-04-05"
    },
    "aliases": [ { "name": "Nirvana US", "sort-name": "Nirvana US" } ],
}

Request: http://musicbrainz.org/ws/2/artist/05cbaf37-6dc2-4f71-a0ce-d633447d90c3?inc=aliases+tags+ratings
Response:

{
    "id": "05cbaf37-6dc2-4f71-a0ce-d633447d90c3",
    "name": "\u6771\u65b9\u795e\u8d77",
    "sort-name": "TVXQ",
    "type": "Group",
    "life-span": { "ended": false, "begin": "2003" },
    "aliases": [
        { "name": "DBSK", "sort-name": "DBSK" },
        { "name": "Tohoshinki", "sort-name": "Tohoshinki", "locale": "ja", "primary": true },
        { "name": "\ub3d9\ubc29\uc2e0\uae30", "sort-name": "\ub3d9\ubc29\uc2e0\uae30", "locale": "ko_KR", "primary": true }
    ],
    "tags": [
        { "count": 1, "name": "kpop" },
        { "count": 1, "name": "jpop" },
        { "count": 1, "name": "cpop" }
    ],
    "rating": { "votes-count": 8, "value": 3.9 }
}

Label

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

{
    "id": "46f0f4cd-8aab-4b33-b698-f459faf64190",
    "name": "Warp Records",
    "sort-name": "Warp Records",
    "label-code": 2070,
    "type": "Original Production",
    "country": "GB",
    "life-span": { "ended": false, "begin": "1989" },
    "tags": [ { "count": 2, "name": "electronic" } ]
}

Request: http://musicbrainz.org/ws/2/label/f49e877d-df8d-4a28-bbe1-689d12fc7d91?inc=aliases
Response:

{
    "id": "f49e877d-df8d-4a28-bbe1-689d12fc7d91"
    "name": "AVEX ENTERTAINMENT INC.",
    "sort-name": "AVEX ENTERTAINMENT INC.",
    "type": "Production",
    "country": "JP",
    "disambiguation": "avex's Japanese music production",
    "life-span": { "ended": false },
    "aliases": [
        { "name": "AVEX MARKETING", "sort-name": "AVEX MARKETING" },
        { "name": "avex marketing", "sort-name": "avex marketing" },
        {
            "name": "\u30a8\u30a4\u30d9\u30c3\u30af\u30b9\u30fb\u30a8\u30f3\u30bf\u30c6\u30a4\u30f3\u30e1\u30f3\u30c8",
            "sort-name": "\u30a8\u30a4\u30d9\u30c3\u30af\u30b9\u30fb\u30a8\u30f3\u30bf\u30c6\u30a4\u30f3\u30e1\u30f3\u30c8"
        }
    ]
}

Recording

Request: http://musicbrainz.org/ws/2/recording/fcbcdc39-8851-4efc-a02a-ab0e13be224f?inc=artist-credits+isrcs+releases
Response:

{
    "id": "fcbcdc39-8851-4efc-a02a-ab0e13be224f",
    "title": "LAST ANGEL"
    "disambiguation": "video"
    "artist-credit": [
        {
            "name": "\u6771\u65b9\u795e\u8d77",
            "joinphrase": " feat. ",
            "artist": {
                "id": "455641ea-fff4-49f6-8fb4-49f961d8f1ac",
                "name": "\u6771\u65b9\u795e\u8d77",
                "sort-name": "Koda, Kumi"
            }
        },
        {
            "name": "\u5016\u7530\u4f86\u672a",
            "artist": {
                "id": "05cbaf37-6dc2-4f71-a0ce-d633447d90c3",
                "name": "\u5016\u7530\u4f86\u672a",
                "sort-name": "TVXQ"
            }
        }
    ],
    "isrcs": [ "JPB600760301" ],
    "length": 228106,
    "releases": [
        {
            "id": "abcd76db-7d5f-3eb7-b386-051c97bfe2e4",
            "title": "Kingdom",
            /* some properties omitted to keep this example shorter. */
        }
    ],
}

Release

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

{
    "id": "59211ea4-ffd2-4ad9-9a4e-941d3148024a",
    "title": "\u00e6\u00b3o & h\u00b3\u00e6",
    "date": "2003-12-04",
    "text-representation": { "language": "eng", "script": "Latn" },
    "country": "GB",
    "status": "Official",
    "quality": "normal",
    "release-group": {
        "id": "bb5622c1-65b2-3bc4-83e6-0dcaa56abaf2",
        "primary-type": "EP"
    },
    "artist-credit": [
        {
            "joinphrase": " & ",
            "name": "Autechre",
            "artist": {
                "id": "410c9baf-5469-44f6-9852-826524b80c61",
                "name": "Autechre",
                "sort-name": "Autechre"
            }
        },
        {
            "name": "The Hafler Trio",
            "artist": {
                "id": "146c01d0-d3a2-44c3-acb5-9208bce75e14",
                "sort-name": "Hafler Trio, The",
                "name": "The Hafler Trio"
            }
        }
    ],
    "labels": [
        {
            "label": {
                "id": "a0759efa-f583-49ea-9a8d-d5bbce55541c",
                "name": "Phonometrography"
            },
            "catalog-number": "pgram002"
        }
    ],
    "media": [
        {
            "title": "\u00e6\u00b3o",
            "format": "CD",
            "discids": [
                { "id": "nN2g3a0ZSjovyIgK3bJl6_.j8C4-", "sectors": 73241 }
            ],
            "tracks": [
                {
                    "number": "1",
                    "length": 974546,
                    "title": "\u00e6\u00b3o",
                    "recording": { /* recording data omitted for this example. */ },
                    "artist-credit": [ /* as on release, not repeated in this example. */ ]
                }
            ]
        },
        {
            "title": "h\u00b3\u00e6",
            "format": "CD",
            "discids": [
                { "id": "aSHvkMnq2jZVFEK.DmSPbvN_f54-", "sectors": 69341 }
            ],
            "tracks": [
                {
                    "number": "1",
                    "length": 922546,
                    "title": "h\u00b3\u00e6",
                    "recording": { /* recording data omitted for this example. */ },
                    "artist-credit": [ /* as on release, not repeated in this example. */ ]
                }
            ]
        }
    ]
}

Release Group

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

{
    "id": "c9fdb94c-4975-4ed6-a96f-ef6d80bb7738",
    "title": "The Lost Tape",
    "artist-credit": [
        "name": "50 Cent",
        "artist": {
            "id": "8e68819d-71be-4e7d-b41d-f1df81b01d3f",
            "name": "50 Cent"
            "sort-name": "50 Cent",
        }
    ],
    "primary-type": "Album",
    "secondary-type": [ "Mixtape/Street" ],
    "releases": [
        {
            "id": "2ec84eb6-ab92-4ac3-9720-32ad84c34f11",
            "title": "The Lost Tape",
            /* some properties omitted to keep this example shorter. */
        }
    ]
}

Work

Request: http://musicbrainz.org/ws/2/work/b1df2cf3-69a9-3bc0-be44-f71e79b27a22
Response:

{
    "id": "b1df2cf3-69a9-3bc0-be44-f71e79b27a22",
    "title": "HELLO! \u307e\u305f\u4f1a\u304a\u3046\u306d",
    "language": "jpn",
    "iswcs": [ "T-101.690.320-9" ]
}

Browse Requests

Browse requests return a toplevel object with offset and count properties to help with paging, and a property for the requested entity. The key for this property will be the english plural of the entity, so: artists, labels, recordings, releases, release-groups or works.

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

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

Relationships

Request: http://musicbrainz.org/ws/2/release/275b01eb-8551-47ff-bd6b-2d142b4bf422?inc=url-rels
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"
        }
    ]
}

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

{
  "id": "b1df2cf3-69a9-3bc0-be44-f71e79b27a22",
  "title": "HELLO! \u307e\u305f\u4f1a\u304a\u3046\u306d",
  "language": "jpn",
  "iswcs": [ "T-101.690.320-9" ],
  "relations": {
    "artist": [       
        {
            "direction": "backward",
            "type": "composer",
            "artist": {
                "id": "d997d399-355e-4c49-9c7b-75a93d76bc0e",
                "name": "\u3064\u3093\u304f\u2642",
                "sort-name": "Tsunku"
            }
        },
        {
            "direction": "backward",
            "type": "lyricist",
            "artist": {
                "id": "d997d399-355e-4c49-9c7b-75a93d76bc0e",
                "name": "\u3064\u3093\u304f\u2642",
                "sort-name": "Tsunku"
            }
        }
    ],
    "recording": [       
        {
            "direction": "backward",
            "type": "performance",
            "recording": {
                "id": "487cac92-eed5-4efa-8563-c9a818079b9a",
                "title": "HELLO! \u307e\u305f\u4f1a\u304a\u3046\u306d (7\u4eba\u796d version)",
                "length": 283600
            }
        },
        {
            "type": "performance",
            "direction": "backward",
            "recording": {
                "id": "fd3061c1-cb9a-4698-bc5f-f6e0e6a36272",
                "title": "HELLO! \u307e\u305f\u4f1a\u304a\u3046\u306d (20\u4eba\u796d version)",
                "disambiguation": "PV"
            }
        }
    ]
  }
}