{
"openapi": "3.1.1",
"info": {
"version": "2.0",
"title": "GMD API v2.0",
"description": "Gracenote Music API Specification\nGMD API V2.0\n"
},
"tags": [
{
"name": "Artists"
},
{
"name": "Recordings"
},
{
"name": "AlbumEditions"
},
{
"name": "Descriptors"
},
{
"name": "Tracks"
}
],
"paths": {
"/artists/search": {
"get": {
"tags": [
"Artists"
],
"summary": "Artist text search",
"description": "Text search for `Artist` objects using artist name.\n",
"parameters": [
{
"$ref": "#/components/parameters/apiKeyParam"
},
{
"$ref": "#/components/parameters/artistName"
},
{
"$ref": "#/components/parameters/limit"
},
{
"$ref": "#/components/parameters/offset"
},
{
"$ref": "#/components/parameters/categoriesLanguage"
},
{
"$ref": "#/components/parameters/genreCategories"
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"meta": {
"$ref": "#/components/schemas/ResponseMeta"
},
"data": {
"type": "array",
"nullable": false,
"items": {
"$ref": "#/components/schemas/ArtistObject"
}
}
},
"required": [
"meta",
"data"
]
}
}
}
},
"400": {
"$ref": "#/components/responses/ErrorResponse400"
},
"404": {
"$ref": "#/components/responses/ErrorResponse404"
}
}
}
},
"/artists/{idType}": {
"get": {
"tags": [
"Artists"
],
"summary": "Lookup Artist(s) by ID",
"description": "Get `Artist` object(s) by ID
\n **Notes**\n * Objects are returned in order requested. \n * If an object is not found, a `null` value is returned in its position.\n * Duplicate ids in the query will result in duplicate objects in the response\n * TMS Party ID lookups require TMS ID add-on.\n * Spotify Artist ID lookups require Spotify IDs add-on.\n\n\n
\n**Example:** Lookup by Gracenote ID
\n`https://.../artists/gnid?ids=GND6CJFDB6BH1X3`\n
\n**Example:** Lookup by tms-music-party-id
\n`https://.../artists/tms-music-party-id?ids=521029`\n
\n**Example:** Lookup by spotify-artist-id
\n`https://.../artists/spotify-artist-id?ids=0d25ed8c5cc94cdbaf8e9961419ed6be`\n\n\n",
"parameters": [
{
"$ref": "#/components/parameters/apiKeyParam"
},
{
"$ref": "#/components/parameters/artistIDType"
},
{
"$ref": "#/components/parameters/ids"
},
{
"$ref": "#/components/parameters/categoriesLanguage"
},
{
"$ref": "#/components/parameters/genreCategories"
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"meta": {
"$ref": "#/components/schemas/ResponseMeta"
},
"data": {
"type": "array",
"nullable": false,
"items": {
"$ref": "#/components/schemas/ArtistObject"
}
}
},
"required": [
"meta",
"data"
]
}
}
}
},
"400": {
"$ref": "#/components/responses/ErrorResponse400"
},
"404": {
"$ref": "#/components/responses/ErrorResponse404"
}
}
}
},
"/recordings/search": {
"get": {
"tags": [
"Recordings"
],
"summary": "Recording text search",
"description": "Text search for `Recording` objects using recording name and/or artist name.\n
\nNote that one of either recording or artist name is required. Omitting both\nwill result in an error.\n",
"parameters": [
{
"$ref": "#/components/parameters/apiKeyParam"
},
{
"$ref": "#/components/parameters/recordingName"
},
{
"$ref": "#/components/parameters/artistName"
},
{
"$ref": "#/components/parameters/isrc"
},
{
"$ref": "#/components/parameters/limit"
},
{
"$ref": "#/components/parameters/offset"
},
{
"$ref": "#/components/parameters/categoriesLanguage"
},
{
"$ref": "#/components/parameters/genreCategories"
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"meta": {
"$ref": "#/components/schemas/ResponseMeta"
},
"data": {
"type": "array",
"nullable": false,
"items": {
"$ref": "#/components/schemas/RecordingObject"
}
}
},
"required": [
"meta",
"data"
]
}
}
}
},
"400": {
"$ref": "#/components/responses/ErrorResponse400"
},
"404": {
"$ref": "#/components/responses/ErrorResponse404"
}
}
}
},
"/recordings/{idType}": {
"get": {
"tags": [
"Recordings"
],
"summary": "Lookup Recording(s) by ID",
"description": "Get `Recording` object(s) by ID
\n\n **Notes**\n * Objects are returned in order requested. \n * If an object is not found, a `null` value is returned in its position.\n * Duplicate ids in the query will result in duplicate objects in the response\n\n
\n**Example:** Lookup by Gracenote ID
\n`https://.../recordings/gnid?ids=GN0TR5Z86C868HS`\n
\n**Example:** Lookup by ISRC
\n`https://.../recordings/isrc?ids=DEY371001140`",
"parameters": [
{
"$ref": "#/components/parameters/apiKeyParam"
},
{
"$ref": "#/components/parameters/recordingIDType"
},
{
"$ref": "#/components/parameters/ids"
},
{
"$ref": "#/components/parameters/categoriesLanguage"
},
{
"$ref": "#/components/parameters/genreCategories"
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"meta": {
"$ref": "#/components/schemas/ResponseMeta"
},
"data": {
"type": "array",
"nullable": false,
"items": {
"$ref": "#/components/schemas/RecordingObject"
}
}
},
"required": [
"meta",
"data"
]
}
}
}
},
"400": {
"$ref": "#/components/responses/ErrorResponse400"
},
"404": {
"$ref": "#/components/responses/ErrorResponse404"
}
}
}
},
"/albumEditions/search": {
"get": {
"tags": [
"AlbumEditions"
],
"summary": "Album text search",
"description": "Text search for `Album` objects using album name and/or artist name.\n
\nNote that one of either album or artist name is required. Omitting both\nwill result in an error.\n",
"parameters": [
{
"$ref": "#/components/parameters/apiKeyParam"
},
{
"$ref": "#/components/parameters/albumName"
},
{
"$ref": "#/components/parameters/artistName"
},
{
"$ref": "#/components/parameters/releaseType"
},
{
"$ref": "#/components/parameters/limit"
},
{
"$ref": "#/components/parameters/offset"
},
{
"$ref": "#/components/parameters/categoriesLanguage"
},
{
"$ref": "#/components/parameters/genreCategories"
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"meta": {
"$ref": "#/components/schemas/ResponseMeta"
},
"data": {
"type": "array",
"nullable": false,
"items": {
"$ref": "#/components/schemas/AlbumObject"
}
}
},
"required": [
"meta",
"data"
]
}
}
}
},
"400": {
"$ref": "#/components/responses/ErrorResponse400"
},
"404": {
"$ref": "#/components/responses/ErrorResponse404"
}
}
}
},
"/albumEditions/{idType}": {
"get": {
"tags": [
"AlbumEditions"
],
"summary": "Lookup Album(s) by ID",
"description": "Get `Album` object(s) by ID
\n\n **Notes**\n * Objects are returned in order requested. \n * If an object is not found, a `null` value is returned in its position.\n * Duplicate ids in the query will result in duplicate objects in the response\n\n
\n**Example:** Lookup by Gracenote ID
\n`https://.../albumEditions/gnid?ids=GN949Y7H6M9XNYP`",
"parameters": [
{
"$ref": "#/components/parameters/apiKeyParam"
},
{
"$ref": "#/components/parameters/albumEditionIDType"
},
{
"$ref": "#/components/parameters/ids"
},
{
"$ref": "#/components/parameters/categoriesLanguage"
},
{
"$ref": "#/components/parameters/genreCategories"
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"meta": {
"$ref": "#/components/schemas/ResponseMeta"
},
"data": {
"type": "array",
"nullable": false,
"items": {
"$ref": "#/components/schemas/AlbumObject"
}
}
},
"required": [
"meta",
"data"
]
}
}
}
},
"400": {
"$ref": "#/components/responses/ErrorResponse400"
},
"404": {
"$ref": "#/components/responses/ErrorResponse404"
}
}
}
},
"/tracks/{idType}": {
"get": {
"tags": [
"Tracks"
],
"description": "licate objects in the response\n",
"parameters": [
{
"$ref": "#/components/parameters/apiKeyParam"
},
{
"$ref": "#/components/parameters/trackIDType"
},
{
"$ref": "#/components/parameters/isrcId"
},
{
"$ref": "#/components/parameters/epc"
},
{
"$ref": "#/components/parameters/limit50"
},
{
"$ref": "#/components/parameters/offset"
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"meta": {
"$ref": "#/components/schemas/ResponseMetaForTracks"
},
"data": {
"type": "array",
"nullable": false,
"items": {
"$ref": "#/components/schemas/TrackObject"
}
}
},
"required": [
"meta",
"data"
]
}
}
}
},
"400": {
"$ref": "#/components/responses/ErrorResponse400"
},
"404": {
"$ref": "#/components/responses/ErrorResponse404"
}
}
}
},
"/descriptorCorrelations/{descriptorType}": {
"get": {
"tags": [
"Descriptors"
],
"parameters": [
{
"$ref": "#/components/parameters/apiKeyParam"
},
{
"$ref": "#/components/parameters/condensedDescriptorType"
},
{
"$ref": "#/components/parameters/categoryIds"
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"meta": {
"$ref": "#/components/schemas/ResponseMeta"
},
"data": {
"type": "array",
"nullable": false,
"items": {
"$ref": "#/components/schemas/DescriptorCorrelationObject"
}
}
},
"required": [
"meta",
"data"
]
}
}
}
},
"400": {
"$ref": "#/components/responses/ErrorResponse400"
},
"404": {
"$ref": "#/components/responses/ErrorResponse404"
}
},
"description": "The descriptor correlation API enables the computation of Artist and Recording similarity by providing numerical values representing that similarity. These similarity values can be used to inform music discovery and catalog navigation models and algorithms.\n
\nThe following workflow illustrates how correlates are used to show that the genre **Psychedelic Rock** is more similar to **Post-Modern Rock** than it is to **Ragtime**.\n
\n1. The `/descriptors/genre` API is used to determine that the `genreID` for \"Psychedelic Rock\" is `2844`.
\n```\ncurl https:///descriptors/genre\n...\n{\n {\n \"ID\": \"2844\",\n \"genericName\": \"Psychedelic Rock\"\n }\n ...\n},\n\n```\n
\n2. The `/descriptors/descriptorCorrelations` API is used with `genreID` value `2844` and the descriptor type set to \"genres\".
\n```\ncurl https:///descriptorCorrelations/genres?ids=2844\n...\n{\n {\n \"ID\": \"33121\",\n \"genre\": \"Post-Modern Rock\",\n \"weight\": \"200\"\n },\n {\n \"ID\": \"3128\",\n \"genre\": \"Ragtime\",\n \"weight\": \"-700\"\n }\n ...\n}\n```\n
\n3. The results show that **Post-Modern Rock** is correlated to **Psychedelic Rock** with a weight of **200** while **Ragtime** is correlated with weight of **-700**. Therefore, **Post-Modern Rock** is the most similar genre.\n",
"summary": "Calculate Artist and Recording similarity"
}
}
},
"servers": [
{
"url": "/proxy/gmd/v2"
}
],
"components": {
"parameters": {
"ids": {
"name": "ids",
"in": "query",
"required": true,
"description": "Comma seperated list of ids (max 100)",
"schema": {
"type": "string"
}
},
"categoryIds": {
"name": "ids",
"in": "query",
"required": true,
"description": "Comma seperated list of category ids (max 100)",
"schema": {
"type": "string"
}
},
"limit": {
"name": "limit",
"in": "query",
"description": "Limit the number of results between 1 and 10,000.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 10000,
"default": 100
}
},
"limit50": {
"name": "limit",
"in": "query",
"description": "Limit the number of results between 1 and 50.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"default": 10
}
},
"offset": {
"name": "offset",
"in": "query",
"description": "Return results starting at the given offset. Used for \"paging\" through results.",
"schema": {
"type": "integer",
"default": 0
}
},
"isrc": {
"name": "isrc",
"in": "query",
"description": "Include ISRC in search criteria. Note that due to ISRC consistency issues (e.g., duplicate or incorrect ISRC), ISRC field matching is a lower priority than text field matching (e.g., artist name).",
"schema": {
"type": "string"
}
},
"isrcId": {
"name": "id",
"in": "query",
"description": "ISRC code to lookup",
"schema": {
"type": "string"
}
},
"epc": {
"name": "albumReleaseCode",
"in": "query",
"description": "UPC/EAN code to lookup",
"schema": {
"type": "string"
}
},
"recordingName": {
"name": "recordingName",
"in": "query",
"description": "Recording name",
"required": true,
"schema": {
"type": "string"
},
"examples": {
"default": {
"value": "Old Town Road"
}
}
},
"artistName": {
"name": "artistName",
"in": "query",
"description": "Artist name",
"required": true,
"schema": {
"type": "string"
},
"examples": {
"default": {
"value": "Lil Nas X"
}
}
},
"albumName": {
"name": "albumName",
"in": "query",
"description": "Album name",
"required": true,
"schema": {
"type": "string"
},
"examples": {
"default": {
"value": "Dark Side of the Moon"
}
}
},
"artistID": {
"name": "artistID",
"in": "query",
"description": "artist GN ID",
"schema": {
"type": "string"
}
},
"albumArtistID": {
"name": "artistID",
"required": true,
"in": "query",
"description": "artist GN ID",
"schema": {
"type": "string"
}
},
"descriptorType": {
"name": "descriptorType",
"in": "path",
"required": true,
"description": "Gracenote descriptor type.",
"schema": {
"type": "string",
"enum": [
"languages",
"scripts",
"eras",
"moods",
"styles",
"tempos",
"artistTypes",
"genres",
"origins"
]
}
},
"condensedDescriptorType": {
"name": "descriptorType",
"in": "path",
"required": true,
"description": "Gracenote descriptor type.",
"schema": {
"type": "string",
"enum": [
"eras",
"moods",
"styles",
"tempos",
"artistTypes",
"genres",
"origins"
]
}
},
"releaseType": {
"name": "releaseType",
"in": "query",
"required": false,
"description": "Select an album release type
\n- 1 - Main Canon
\n- 2 - Main Canon Collection
\n- 3 - Single Artist Collection
\n- 4 - Multi Artist Collection
\n- 10 - Single
",
"schema": {
"type": "integer",
"enum": [
1,
2,
3,
4,
10
]
}
},
"categoriesLanguage": {
"name": "categoriesLanguage",
"in": "query",
"required": false,
"description": "Result localization language code.",
"schema": {
"type": "string",
"enum": [
"ar",
"bg",
"zh-Hans",
"zh-Hant",
"hr",
"cs",
"da",
"nl",
"en",
"fi",
"fr",
"de",
"el",
"hu",
"id",
"it",
"ja",
"ko",
"nb",
"fa",
"pl",
"pt",
"ro",
"ru",
"sr",
"sk",
"es",
"sv",
"th",
"tr",
"vi"
]
}
},
"genreCategories": {
"name": "genreCategories",
"in": "query",
"required": false,
"description": "Select a genre categories according to the desired region and specificity.",
"schema": {
"type": "string",
"enum": [
"GENRES-US-DETAILED",
"GENRES-US-SIMPLIFIED",
"GENRES-CHINA-DETAILED",
"GENRES-CHINA-SIMPLIFIED",
"GENRES-EUROPE-DETAILED",
"GENRES-EUROPE-SIMPLIFIED",
"GENRES-GLOBAL-DETAILED",
"GENRES-GLOBAL-SIMPLIFIED",
"GENRES-INDIA-SIMPLIFIED",
"GENRES-JAPAN-DETAILED",
"GENRES-JAPAN-SIMPLIFIED",
"GENRES-KOREA-DETAILED",
"GENRES-KOREA-SIMPLIFIED",
"GENRES-LATIN-AMERICA-DETAILED",
"GENRES-LATIN-AMERICA-SIMPLIFIED",
"GENRES-TAIWAN-DETAILED",
"GENRES-TAIWAN-SIMPLIFIED"
]
}
},
"genreCategoriesID": {
"name": "genreCategoriesID",
"in": "query",
"required": false,
"description": "Select a genre hierarchy code according to the desired region and specificity.
\n- 83 - US-DETAILED
\n- 84 - US-SIMPLIFIED
\n- 90 - CHINA-DETAILED
\n- 91 - CHINA-SIMPLIFIED
\n- 121 - EUROPE-DETAILED
\n- 122 - EUROPE-SIMPLIFIED
\n- 87 - GLOBAL-DETAILED
\n- 88 - GLOBAL-SIMPLIFIED
\n- 158 - INDIA-SIMPLIFIED
\n- 85 - JAPAN-DETAILED
\n- 86 - JAPAN-SIMPLIFIED
\n- 119 - KOREA-DETAILED
\n- 112 - KOREA-SIMPLIFIED
\n- 159 - LATIN-AMERICA-DETAILED
\n- 154 - LATIN-AMERICA-SIMPLIFIED
\n- 92 - TAIWAN-DETAILED
\n- 93 - TAIWAN-SIMPLIFIED
",
"schema": {
"type": "integer",
"enum": [
90,
91,
121,
122,
87,
88,
158,
85,
86,
119,
112,
159,
154,
92,
93,
83,
84
]
}
},
"artistIDType": {
"name": "idType",
"in": "path",
"required": true,
"description": "ID Type",
"schema": {
"type": "string",
"enum": [
"gnid",
"tms-music-party-id",
"spotify-artist-id"
]
}
},
"recordingIDType": {
"name": "idType",
"in": "path",
"required": true,
"description": "ID Type",
"schema": {
"type": "string",
"enum": [
"gnid",
"isrc",
"appletrackid",
"spotify-track-id",
"deezer-global-track-id"
]
}
},
"trackIDType": {
"name": "idType",
"in": "path",
"required": true,
"description": "ID Type",
"schema": {
"type": "string",
"enum": [
"isrc"
]
}
},
"albumEditionIDType": {
"name": "idType",
"in": "path",
"required": true,
"description": "ID Type",
"schema": {
"type": "string",
"enum": [
"gnid",
"upc",
"applealbumid",
"spotify-album-id",
"deezer-global-album-id"
]
}
},
"apiKeyParam": {
"name": "GN-APIKEY",
"in": "header",
"description": "API key to authorize the request.",
"required": true,
"schema": {
"type": "string",
"examples": [
"your-api-key"
]
}
}
},
"schemas": {
"Artist": {
"type": "object",
"properties": {
"artistID": {
"type": [
"string",
"null"
],
"description": "gracenote ID"
},
"artistName": {
"type": "string"
},
"href": {
"type": [
"string",
"null"
],
"description": "will be of the type /artists/gnid?ids=GNXX"
}
}
},
"ArtistMember": {
"type": "object",
"properties": {
"artistID": {
"type": [
"string",
"null"
],
"description": "gracenote ID"
},
"artistName": {
"type": "string"
},
"href": {
"type": [
"string",
"null"
],
"description": "will be of the type /artists/gnid?ids=GNXX"
},
"ord": {
"type": "integer",
"description": "order number for sorting"
}
}
},
"ArtistWithImage": {
"type": "object",
"properties": {
"artistID": {
"type": [
"string",
"null"
],
"description": "gracenote ID"
},
"artistName": {
"type": "string"
},
"href": {
"type": [
"string",
"null"
],
"description": "will be of the type /artists/gnid?ids=GNXX"
},
"images": {
"type": [
"array",
"null"
],
"description": "Only visible to Customers with Artist Images add-on",
"items": {
"$ref": "#/components/schemas/Image"
}
}
}
},
"Popularity": {
"type": "object",
"properties": {
"region": {
"type": "string"
},
"score": {
"type": "number"
},
"type": {
"type": "string"
}
}
},
"LanguageContext": {
"type": [
"object",
"null"
],
"properties": {
"language": {
"type": [
"string",
"null"
]
},
"script": {
"type": [
"string",
"null"
]
}
}
},
"LanguageContextWeight": {
"type": [
"object",
"null"
],
"properties": {
"language": {
"type": [
"string",
"null"
]
},
"script": {
"type": [
"string",
"null"
]
},
"weight": {
"type": [
"integer",
"null"
]
}
}
},
"LanguageContextWeightID": {
"type": [
"object",
"null"
],
"properties": {
"languageID": {
"type": [
"string",
"null"
]
},
"language": {
"type": [
"string",
"null"
]
},
"script": {
"type": [
"string",
"null"
]
},
"weight": {
"type": [
"integer",
"null"
]
}
}
},
"ArtistName": {
"type": "object",
"properties": {
"artistName": {
"type": "string"
},
"languageContext": {
"$ref": "#/components/schemas/LanguageContext"
}
}
},
"Languages": {
"type": "array",
"description": "Only visible to Customers with GMD:Discovery package and above",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"ID": {
"type": "string"
},
"name": {
"type": "string"
},
"weight": {
"type": "integer",
"description": "Only visible to Customers with GMD:Advanced Discovery package and above"
}
}
}
},
"ReleaseType": {
"type": [
"string",
"null"
],
"description": "Only visible to Customers with GMD:Discovery package and above"
},
"Image": {
"type": "object",
"properties": {
"size": {
"type": "string"
},
"height": {
"type": "integer"
},
"width": {
"type": "integer"
},
"url": {
"type": "string",
"pattern": "^https://"
}
}
},
"DescriptorObject": {
"type": "array",
"description": "Only visible to Customers with GMD Discovery/Advanced Discovery package.",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"ID": {
"type": "string"
},
"name": {
"type": "string"
},
"weight": {
"type": "integer"
},
"categories": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"level": {
"type": "integer"
}
}
}
},
"links": {
"type": "object",
"properties": {
"descriptorCorrelations": {
"description": "Only visible to Customers with GMD:Advanced Discovery package and above. will be of the type /descriptorCorrelations/{descriptorType}?id=ID",
"type": "string"
}
}
}
}
}
},
"DescriptorCorrelationObject": {
"type": "object",
"properties": {
"ID": {
"type": "string"
},
"descriptorType": {
"type": "string"
},
"correlations": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CorrelationObject"
}
}
}
},
"CorrelationObject": {
"type": "object",
"properties": {
"ID": {
"type": "string"
},
"name": {
"type": "string"
},
"correlationValue": {
"type": "integer"
},
"links": {
"type": "object",
"properties": {
"descriptorCorrelations": {
"description": "Only visible to Customers with GMD:Advanced Discovery package and above. will be of the type /descriptorCorrelations/{descriptorType}?id=ID",
"type": "string"
}
}
}
}
},
"ExternalID": {
"type": "object",
"properties": {
"source": {
"type": "string"
},
"ID": {
"type": "string"
}
}
},
"Track": {
"type": "object",
"properties": {
"artist": {
"$ref": "#/components/schemas/Artist"
},
"ord": {
"type": "string"
},
"recording": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "will be of the type /recordings/gnid?ids=GNXX"
},
"recordingID": {
"type": "string"
}
}
},
"trackName": {
"type": "string"
}
}
},
"ArtistObject": {
"type": [
"object",
"null"
],
"properties": {
"type": {
"type": "string",
"description": "its value should be [artists]"
},
"alternateNames": {
"description": "Only visible to Customers with GMD:Search package and above",
"type": [
"array",
"null"
],
"items": {
"$ref": "#/components/schemas/ArtistName"
}
},
"artistID": {
"description": "gracenote ID",
"type": "string"
},
"href": {
"description": "will be of the type /artists/gnid?ids=ID",
"type": "string"
},
"artistName": {
"$ref": "#/components/schemas/ArtistName"
},
"sortName": {
"type": [
"string",
"null"
]
},
"descriptors": {
"type": [
"object",
"null"
],
"properties": {
"artistTypes": {
"$ref": "#/components/schemas/DescriptorObject"
},
"eras": {
"$ref": "#/components/schemas/DescriptorObject"
},
"genres": {
"$ref": "#/components/schemas/DescriptorObject"
},
"languages": {
"$ref": "#/components/schemas/Languages"
},
"origins": {
"$ref": "#/components/schemas/DescriptorObject"
}
}
},
"disambiguation": {
"type": [
"string",
"null"
],
"description": "Only visible to Customers with GMD:Search package and above"
},
"externalIDs": {
"type": [
"array",
"null"
],
"description": "Only visible to Customers with Spotify IDs Add on",
"items": {
"$ref": "#/components/schemas/ExternalID"
}
},
"personIDs": {
"type": [
"array",
"null"
],
"description": "Only visible to Customers with Links to video celebrities Add On",
"items": {
"nullable": false,
"type": "string"
}
},
"images": {
"type": [
"array",
"null"
],
"description": "Only visible to Customers with Artist Images add-on",
"items": {
"$ref": "#/components/schemas/Image"
}
},
"nameVariants": {
"type": [
"array",
"null"
],
"description": "Only visible to Customers with GMD:Search package and above",
"items": {
"type": "string"
}
},
"objectType": {
"type": [
"string",
"null"
]
},
"popularity": {
"type": [
"array",
"null"
],
"description": "Only visible to Customers with Popularity Add On",
"items": {
"$ref": "#/components/schemas/Popularity"
}
},
"bandMembers": {
"type": [
"array",
"null"
],
"description": "Only visible to Customers with GMD:Search package and above",
"items": {
"$ref": "#/components/schemas/ArtistMember"
}
},
"collaborationMembers": {
"type": [
"array",
"null"
],
"description": "Only visible to Customers with GMD:Search package and above",
"items": {
"$ref": "#/components/schemas/ArtistMember"
}
},
"keyArtists": {
"type": [
"array",
"null"
],
"description": "Only visible to Customers with GMD:Search package and above",
"items": {
"$ref": "#/components/schemas/Artist"
}
},
"memberOfBands": {
"type": [
"array",
"null"
],
"description": "Only visible to Customers with GMD:Search package and above",
"items": {
"$ref": "#/components/schemas/Artist"
}
},
"memberOfCollaborations": {
"type": [
"array",
"null"
],
"description": "Only visible to Customers with GMD:Search package and above",
"items": {
"$ref": "#/components/schemas/Artist"
}
},
"similarArtists": {
"type": [
"array",
"null"
],
"description": "Only visible to Customers with GMD:Advanced Discovery Package",
"items": {
"$ref": "#/components/schemas/Artist"
}
}
}
},
"RecordingObject": {
"type": [
"object",
"null"
],
"properties": {
"type": {
"type": "string",
"description": "[recordings]"
},
"artist": {
"$ref": "#/components/schemas/ArtistWithImage"
},
"descriptors": {
"description": "Only visible to Customers with GMD Discovery/Advanced Discovery package",
"type": [
"object",
"null"
],
"properties": {
"artistTypes": {
"$ref": "#/components/schemas/DescriptorObject"
},
"eras": {
"$ref": "#/components/schemas/DescriptorObject"
},
"genres": {
"$ref": "#/components/schemas/DescriptorObject"
},
"moods": {
"$ref": "#/components/schemas/DescriptorObject"
},
"origins": {
"$ref": "#/components/schemas/DescriptorObject"
},
"styles": {
"$ref": "#/components/schemas/DescriptorObject"
},
"tempos": {
"$ref": "#/components/schemas/DescriptorObject"
}
}
},
"duration": {
"type": "string"
},
"externalIDs": {
"type": [
"array",
"null"
],
"description": "Only visible to Customers with Partner IDs Add on",
"items": {
"$ref": "#/components/schemas/ExternalID"
}
},
"href": {
"description": "will be of the type /recordings/gnid?ids=GNXX",
"type": "string"
},
"popularity": {
"type": [
"array",
"null"
],
"description": "Only visible to Customers with Popularity Add On",
"items": {
"$ref": "#/components/schemas/Popularity"
}
},
"isrcs": {
"type": [
"array",
"null"
],
"description": "Only visible to Customers with Industry IDs Add on",
"items": {
"type": "string",
"nullable": false,
"pattern": "^[A-Z]{2}[A-Z0-9]{3}\\d{7}$"
}
},
"recordingID": {
"description": "gracenote ID",
"type": "string"
},
"recordingName": {
"type": "string"
},
"releaseYear": {
"description": "Only visible to Customers with GMD:Search Package",
"type": [
"string",
"null"
]
},
"selectedAlbumEdition": {
"type": "object",
"description": "Only visible to Customers Search Package",
"properties": {
"href": {
"type": "string"
},
"selectedAlbumEditionID": {
"type": "string"
},
"selectedAlbumEditionName": {
"type": "string"
},
"images": {
"type": [
"array",
"null"
],
"description": "Only visible to Customers with Cover Art add-on",
"items": {
"$ref": "#/components/schemas/Image"
}
}
}
}
}
},
"AlbumObject": {
"type": [
"object",
"null"
],
"properties": {
"type": {
"type": "string",
"description": "[albums]"
},
"albumEditionID": {
"description": "gracenote ID",
"type": "string"
},
"albumEditionName": {
"type": "string"
},
"artist": {
"$ref": "#/components/schemas/ArtistWithImage"
},
"externalIDs": {
"type": [
"array",
"null"
],
"description": "Only visible to Customers with Partner IDs add on",
"items": {
"$ref": "#/components/schemas/ExternalID"
}
},
"href": {
"type": "string"
},
"images": {
"type": [
"array",
"null"
],
"description": "Only visible to Customers with Cover Art add-on",
"items": {
"$ref": "#/components/schemas/Image"
}
},
"languageContexts": {
"type": [
"array",
"null"
],
"description": "Only visible to Customers with GMD:Discovery package and above",
"items": {
"$ref": "#/components/schemas/LanguageContextWeight"
}
},
"selectedAlbumEdition": {
"type": "object",
"description": "Only visible to Customers Search Package",
"properties": {
"href": {
"type": "string"
},
"selectedAlbumEditionID": {
"type": "string"
}
}
},
"releaseType": {
"$ref": "#/components/schemas/ReleaseType"
},
"releaseYear": {
"description": "Only visible to Customers with GMD:Search package",
"type": [
"string",
"null"
]
},
"trackCount": {
"type": [
"integer",
"null"
]
},
"tracks": {
"type": [
"array",
"null"
],
"items": {
"$ref": "#/components/schemas/Track"
}
},
"descriptors": {
"type": [
"object",
"null"
],
"properties": {
"genres": {
"$ref": "#/components/schemas/DescriptorObject"
}
}
}
}
},
"TrackObject": {
"type": "object",
"properties": {
"type": {
"description": "type of the object: [tracks]",
"type": "string"
},
"trackID": {
"description": "trackID",
"type": "string"
},
"isrc": {
"description": "track ISRC",
"type": "string"
},
"trackName": {
"description": "trackName",
"type": "string"
},
"album": {
"$ref": "#/components/schemas/TrackAlbum"
},
"artist": {
"$ref": "#/components/schemas/TrackArtist"
},
"descriptors": {
"$ref": "#/components/schemas/SonicDescriptors"
}
}
},
"TrackAlbum": {
"type": "object",
"properties": {
"albumID": {
"description": "albumID",
"type": "string"
},
"albumName": {
"description": "albumName",
"type": "string"
}
}
},
"TrackArtist": {
"type": "object",
"properties": {
"artistID": {
"description": "artistID",
"type": "string"
},
"artistName": {
"description": "artistName",
"type": "string"
}
}
},
"SonicDescriptors": {
"type": [
"object",
"null"
],
"description": "Only visible to Customers with GMD Discovery/Advanced Discovery package",
"properties": {
"moods": {
"$ref": "#/components/schemas/DescriptorObject"
},
"styles": {
"$ref": "#/components/schemas/DescriptorObject"
},
"tempos": {
"$ref": "#/components/schemas/DescriptorObject"
}
}
},
"ResponseMeta": {
"type": "object",
"nullable": false,
"additionalProperties": false,
"properties": {
"total": {
"type": "integer",
"nullable": false
},
"count": {
"type": "integer",
"nullable": false
},
"offset": {
"type": "integer",
"nullable": false
},
"references": {
"type": "object",
"properties": {
"genreCategories": {
"type": "string"
},
"categoriesLanguage": {
"type": "string"
}
}
}
},
"required": [
"total",
"count",
"offset"
]
},
"ResponseMetaForTracks": {
"type": "object",
"nullable": false,
"additionalProperties": false,
"properties": {
"total": {
"type": "integer",
"nullable": false
},
"count": {
"type": "integer",
"nullable": false
},
"offset": {
"type": "integer",
"nullable": false
},
"references": {
"type": "object",
"additionalProperties": false,
"properties": {
"categoriesLanguage": {
"type": "string"
}
}
}
},
"required": [
"total",
"count",
"offset"
]
},
"ErrorResponse": {
"type": "object",
"nullable": false,
"additionalProperties": false,
"properties": {
"status": {
"type": "integer",
"nullable": false
},
"error": {
"type": "string",
"nullable": false
},
"description": {
"type": "string",
"nullable": false
}
},
"required": [
"status",
"error",
"description"
]
}
},
"responses": {
"ErrorResponse400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"default": {
"value": {
"status": 400,
"error": "invalid_query_parameter_value",
"description": "Data Type Error: explicitLanguage must be of type boolean."
}
}
}
}
}
},
"ErrorResponse401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"default": {
"value": {
"status": 401,
"error": "unauthorized_missing_apikey",
"description": "API key is required."
}
}
}
}
}
},
"ErrorResponse403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"default": {
"value": {
"status": 403,
"error": "plan_limit_exceeded",
"description": "Number of queries exceeds plan limit."
}
}
}
}
}
},
"ErrorResponse404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"default": {
"value": {
"status": 404,
"error": "resource_not_found",
"description": "Parameter given is not found."
}
}
}
}
}
},
"ErrorResponse413": {
"description": "Payload Too Large",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"default": {
"value": {
"status": 413,
"error": "request_too_large",
"description": "Size of request exceeds 3MB."
}
}
}
}
}
},
"ErrorResponse429": {
"description": "Too Many Requests",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"default": {
"value": {
"status": 429,
"error": "rate_limit_exceeded",
"description": "Number of queries per minute exceeds limit."
}
}
}
}
}
}
}
}
}