From 8e3bd9c5b4739d5f38104902447b3f2330159e24 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Mon, 6 Apr 2026 21:51:44 -0400 Subject: [PATCH 1/2] docs: add GET /api/research/track/playlists endpoint OpenAPI spec with parameters (id, q, platform, status, editorial, sort, limit, offset, since, until), response schema (ResearchTrackPlaylistsResponse), and 400/401 error responses. Navigation entry added after track page. Made-with: Cursor --- api-reference/openapi.json | 192 +++++++++++++++++++++ api-reference/research/track-playlists.mdx | 4 + docs.json | 1 + 3 files changed, 197 insertions(+) create mode 100644 api-reference/research/track-playlists.mdx diff --git a/api-reference/openapi.json b/api-reference/openapi.json index 2393a65..4d25fee 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -6913,6 +6913,149 @@ } } }, + "/api/research/track/playlists": { + "get": { + "description": "Get playlists featuring a specific track — editorial, algorithmic, and indie. Returns playlist name, cover image, follower count, and curator.", + "parameters": [ + { + "name": "id", + "in": "query", + "required": false, + "description": "Chartmetric track ID. Provide this or `q`.", + "schema": { + "type": "string" + } + }, + { + "name": "q", + "in": "query", + "required": false, + "description": "Track name to search for. Provide this or `id`.", + "schema": { + "type": "string" + } + }, + { + "name": "platform", + "in": "query", + "required": false, + "description": "Streaming platform.", + "schema": { + "type": "string", + "enum": ["spotify", "applemusic", "deezer", "amazon"], + "default": "spotify" + } + }, + { + "name": "status", + "in": "query", + "required": false, + "description": "Playlist status.", + "schema": { + "type": "string", + "enum": ["current", "past"], + "default": "current" + } + }, + { + "name": "editorial", + "in": "query", + "required": false, + "description": "Only editorial playlists.", + "schema": { + "type": "boolean" + } + }, + { + "name": "since", + "in": "query", + "required": false, + "description": "Filter by start date (YYYY-MM-DD).", + "schema": { + "type": "string" + } + }, + { + "name": "until", + "in": "query", + "required": false, + "description": "Filter by end date (YYYY-MM-DD).", + "schema": { + "type": "string" + } + }, + { + "name": "sort", + "in": "query", + "required": false, + "description": "Sort results by this field (e.g. followers, added_at, position).", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "Maximum number of results (max 100).", + "schema": { + "type": "integer", + "default": 10 + } + }, + { + "name": "offset", + "in": "query", + "required": false, + "description": "Offset for pagination.", + "schema": { + "type": "integer", + "default": 0 + } + } + ], + "responses": { + "200": { + "description": "Playlists featuring the track", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchTrackPlaylistsResponse" + } + } + } + }, + "400": { + "description": "Missing or invalid parameters", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "status": { "type": "string", "example": "error" }, + "error": { "type": "string" } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "status": { "type": "string", "example": "error" }, + "error": { "type": "string" } + } + } + } + } + } + } + } + }, "/api/research/tracks": { "get": { "description": "Get all tracks by an artist with popularity data.", @@ -15087,6 +15230,55 @@ } } }, + "ResearchTrackPlaylistsResponse": { + "type": "object", + "properties": { + "status": { + "type": "string", + "example": "success" + }, + "placements": { + "type": "array", + "items": { + "type": "object", + "properties": { + "playlist": { + "type": "object", + "properties": { + "name": { "type": "string", "description": "Playlist name" }, + "image_url": { "type": "string", "description": "Playlist cover image URL" }, + "playlist_id": { "type": "string", "description": "Spotify playlist ID" }, + "id": { "type": "integer", "description": "Chartmetric playlist ID" }, + "description": { "type": "string" }, + "followers": { "type": "integer", "description": "Playlist follower count" }, + "num_track": { "type": "integer", "description": "Number of tracks" }, + "editorial": { "type": "boolean", "description": "Whether playlist is editorial" }, + "owner_name": { "type": "string", "description": "Playlist curator name" }, + "position": { "type": "integer", "description": "Track position in playlist" }, + "peak_position": { "type": "integer", "description": "Track peak position" }, + "added_at": { "type": "string", "description": "When track was added" }, + "tags": { "type": "array", "items": { "type": "object" } } + }, + "additionalProperties": true + }, + "track": { + "type": "object", + "properties": { + "name": { "type": "string", "description": "Track name" }, + "cm_track": { "type": "integer", "description": "Chartmetric track ID" }, + "isrc": { "type": "string", "description": "Track ISRC" }, + "image_url": { "type": "string", "description": "Track image URL" }, + "artist_names": { "type": "array", "items": { "type": "string" } }, + "spotify_popularity": { "type": "integer" } + }, + "additionalProperties": true + } + }, + "additionalProperties": true + } + } + } + }, "ResearchProfileResponse": { "type": "object", "description": "Full artist profile \u2014 bio, genres, social links, label, images, and basic stats.", diff --git a/api-reference/research/track-playlists.mdx b/api-reference/research/track-playlists.mdx new file mode 100644 index 0000000..b6d2cdd --- /dev/null +++ b/api-reference/research/track-playlists.mdx @@ -0,0 +1,4 @@ +--- +title: 'Track Playlists' +openapi: 'GET /api/research/track/playlists' +--- diff --git a/docs.json b/docs.json index 11c47fb..404b7a2 100644 --- a/docs.json +++ b/docs.json @@ -163,6 +163,7 @@ "api-reference/research/albums", "api-reference/research/tracks", "api-reference/research/track", + "api-reference/research/track-playlists", "api-reference/research/career", "api-reference/research/insights", "api-reference/research/playlist", From 680b81a1b43ff2ddc78ce2fa296d0b72f9776c1d Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Mon, 6 Apr 2026 22:57:47 -0400 Subject: [PATCH 2/2] docs: add artist param to track/playlists endpoint Improves track search accuracy when using q= by allowing artist name to narrow Spotify search results. Made-with: Cursor --- api-reference/openapi.json | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/api-reference/openapi.json b/api-reference/openapi.json index 4d25fee..4707023 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -6935,6 +6935,15 @@ "type": "string" } }, + { + "name": "artist", + "in": "query", + "required": false, + "description": "Artist name — improves track search accuracy when using `q`.", + "schema": { + "type": "string" + } + }, { "name": "platform", "in": "query",