MusicBrainz API/Examples: Difference between revisions

From MusicBrainz Wiki
Jump to navigationJump to search
No edit summary
Line 150: Line 150:
"country": "GB",
"country": "GB",
"status": "Official",
"status": "Official",
"quality": "normal",
"release-group": {
"release-group": {
"id": "bb5622c1-65b2-3bc4-83e6-0dcaa56abaf2",
"id": "bb5622c1-65b2-3bc4-83e6-0dcaa56abaf2",
Line 264: Line 265:
==Browse Requests==
==Browse Requests==


Browse requests return a toplevel object with offset and count properties to help with paging, and a property for the requested entity.
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.
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<br />
Request: http://musicbrainz.org/ws/2/release?label=47e718e1-7ee4-460c-b1cc-1192a841c6e5&offset=12&limit=2<br />
Line 288: Line 291:
}
}
</code>
</code>

==Relationships==

Request: http://musicbrainz.org/ws/2/release/275b01eb-8551-47ff-bd6b-2d142b4bf422?inc=url-rels<br />
Response:

<code>
{
"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"
}
]
}
</code>

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

<code>
{
"id": "b1df2cf3-69a9-3bc0-be44-f71e79b27a22",
"title": "HELLO! \u307e\u305f\u4f1a\u304a\u3046\u306d",
"language": "jpn",
"iswcs": [ "T-101.690.320-9" ],
"relations": [
{
"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"
}
},
{
"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"
}
}
]
}

Revision as of 11:49, 6 July 2012

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.

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